platform-api

Platform API Extraction Skill

Overview

This skill provides jq query patterns for extracting API endpoint information from the Genesys Cloud Platform API Swagger 2.0 schema. The schema contains over 1,900 endpoints and 4,305 definitions in a 19MB+ file.

Schema: schema.json must be downloaded before first use. Run the download script from this skill's directory:

./scripts/download-schema.sh

See the download script for region options and usage details.

Before running any queries, determine the absolute path to this SKILL.md file's parent directory and set the schema path variable:

SCHEMA="<resolved-skill-directory>/schema.json"

All examples below use "$SCHEMA" to reference this file.

---

MANDATORY WORKFLOW

CRITICAL: NEVER recommend endpoints without verification!

When asked about an endpoint or API operation, you MUST follow this 4-step workflow:

PERFORMANCE REQUIREMENT: Execute Queries in PARALLEL

Steps 1-3 are INDEPENDENT queries. Execute them in a SINGLE message using multiple Bash tool calls in parallel.

Step 1: Search & Verify

Search for matching endpoints (ALWAYS limit to 15-20 results):

jq -r '.paths | keys | map(select(test("KEYWORD"; "i"))) | .[0:15] | .[]' "$SCHEMA"

Common patterns: "find all X" -> /api/v2/X$, "get specific X" -> /api/v2/X/\{id\}

See references/search-operations.md for detailed search patterns.

Step 2: Confirm Exact Endpoint Exists

jq '.paths["/api/v2/exact/path"] | keys' "$SCHEMA"

If this returns null, the endpoint does not exist. Do NOT proceed.

Step 3: Extract Full Operation Details

jq '.paths["/api/v2/exact/path"]["METHOD"] | {
  operationId,
  summary,
  description,
  permissions: ."x-inin-requires-permissions",
  parameters: [.parameters[]? | {name, in, required, type, description}]
}' "$SCHEMA"

Replace METHOD with: get, post, put, patch, or delete.

See references/jq-query-patterns.md for complete extraction patterns and references/schema-resolution.md for resolving $ref references.