feat: add apify api subcommand for direct API access

docs/reference.md

@@ -44,6 +44,50 @@ FLAGS
                          not provided, the latest version will be used.
 ```
 
+##### `apify api`
+
+```sh
+DESCRIPTION
+  Makes an authenticated HTTP request to the Apify API and prints the response.
+  The endpoint can be a relative path (e.g. "acts", "v2/acts", or "/v2/acts").
+  The "v2/" prefix is added automatically if omitted.
+
+  You can also pass the HTTP method before the endpoint:
+    apify api GET /v2/actor-runs
+    apify api POST /v2/acts -d '{"name": "my-actor"}'
+
+  Use --params/-p to pass query parameters as JSON:
+    apify api actor-runs -p '{"limit": 1, "desc": true}'
+
+  Use --list-endpoints to see all available API endpoints.
+  For full documentation, see https://docs.apify.com/api/v2
+
+USAGE
+  $ apify api [methodOrEndpoint] [endpoint] [-d <value>] [-H <value>]
+              [-l] [-X GET|POST|PUT|PATCH|DELETE] [-p <value>]
+
+ARGUMENTS
+  methodOrEndpoint  The API endpoint path (e.g. "acts",
+                    "v2/acts", "/v2/users/me"), or an HTTP method followed by the
+                    endpoint (e.g. "GET /v2/users/me").
+  endpoint          The API endpoint path when the first
+                    argument is an HTTP method.
+
+FLAGS
+  -d, --body=<value>     The request body (JSON string). Use
+                         "-" to read from stdin.
+      -H, --header=<value>   Additional HTTP header(s). Pass a
+                         single "key:value" string, or a JSON object like '{"X-Foo":
+                         "bar", "X-Baz": "qux"}' to send multiple headers.
+  -l, --list-endpoints   List all available Apify API
+                         endpoints.
+      -X, --method=<option>  The HTTP method to use. Defaults to
+                         GET.
+                         <options: GET|POST|PUT|PATCH|DELETE>
+  -p, --params=<value>   Query parameters as a JSON object,
+                         e.g. '{"limit": 1, "desc": true}'.
+```
+
 ##### `apify telemetry`
 
 ```sh

package.json

@@ -17,9 +17,10 @@
         "format": "biome format . && prettier --check \"**/*.{md,yml,yaml}\"",
         "format:fix": "biome format --write . && prettier --write \"**/*.{md,yml,yaml}\"",
         "clean": "rimraf dist",
+        "fetch-api-endpoints": "tsx scripts/fetch-api-endpoints.ts",
         "build": "yarn clean && tsc && tsup",
         "build-bundles": "bun run scripts/build-cli-bundles.ts",
-        "prepack": "yarn insert-cli-metadata && yarn build && yarn update-docs",
+        "prepack": "yarn insert-cli-metadata && (yarn fetch-api-endpoints || echo 'Warning: Failed to fetch API endpoints, using existing file') && yarn build && yarn update-docs",
         "insert-cli-metadata": "tsx scripts/insert-cli-metadata.ts",
         "update-docs": "tsx scripts/generate-cli-docs.ts",
         "postinstall": "node -e \"console.log('We have an active developer community on Discord. You can find it on https://discord.gg/crawlee-apify-801163717915574323.');\"",

scripts/fetch-api-endpoints.ts

@@ -0,0 +1,52 @@
+/**
+ * Fetches the Apify OpenAPI spec and extracts a minimal endpoint catalog
+ * (method, path, summary) for use by the `apify api --list-endpoints` flag.
+ */
+
+import { writeFile } from 'node:fs/promises';
+
+const OPENAPI_URL = 'https://docs.apify.com/api/openapi.json';
+const OUTPUT_PATH = new URL('../src/commands/api-endpoints.json', import.meta.url);
+
+interface OpenAPISpec {
+	paths: Record<string, Record<string, { summary?: string }>>;
+}
+
+interface Endpoint {
+	method: string;
+	path: string;
+	summary: string;
+}
+
+const HTTP_METHODS = new Set(['get', 'post', 'put', 'patch', 'delete']);
+
+console.log(`Fetching OpenAPI spec from ${OPENAPI_URL}...`);
+
+const response = await fetch(OPENAPI_URL);
+
+if (!response.ok) {
+	throw new Error(`Failed to fetch OpenAPI spec: ${response.status} ${response.statusText}`);
+}
+
+const spec = (await response.json()) as OpenAPISpec;
+
+const endpoints: Endpoint[] = [];
+
+for (const [path, methods] of Object.entries(spec.paths)) {
+	for (const [method, details] of Object.entries(methods)) {
+		if (HTTP_METHODS.has(method)) {
+			endpoints.push({
+				method: method.toUpperCase(),
+				path,
+				summary: details.summary || '',
+			});
+		}
+	}
+}
+
+// Sort by path, then method
+endpoints.sort((a, b) => a.path.localeCompare(b.path) || a.method.localeCompare(b.method));
+
+await writeFile(OUTPUT_PATH, `${JSON.stringify(endpoints, null, '\t')}\n`);
+
+console.log(`Extracted ${endpoints.length} endpoints to ${OUTPUT_PATH.pathname}`);

scripts/generate-cli-docs.ts

@@ -75,6 +75,7 @@ const categories: Record<string, CommandsInCategory[]> = {
 		//
 		{ command: Commands.help },
 		{ command: Commands.upgrade },
+		{ command: Commands.api },
 		{ command: Commands.telemetry },
 		{ command: Commands.telemetryEnable },
 		{ command: Commands.telemetryDisable },

src/commands/_register.ts

@@ -9,6 +9,7 @@ import { ActorGetValueCommand } from './actor/get-value.js';
 import { ActorPushDataCommand } from './actor/push-data.js';
 import { ActorSetValueCommand } from './actor/set-value.js';
 import { ActorsIndexCommand } from './actors/_index.js';
+import { ApiCommand } from './api.js';
 import { AuthIndexCommand } from './auth/_index.js';
 import { BuildsIndexCommand } from './builds/_index.js';
 import { TopLevelCallCommand } from './call.js';
@@ -49,6 +50,7 @@ export const apifyCommands = [
 	TelemetryIndexCommand,
 
 	// top-level
+	ApiCommand,
 	TopLevelCallCommand,
 	UpgradeCommand,
 	InstallCommand,