API Discovery and Safety

Required Inputs

Gateway API base URL. When using the bundled Web deployment this commonly includes /gateway-api; direct API access commonly uses port 8088.
Administrator JWT with the manager or admin role.
Target provider documentation and authorization material.
Clear requested outcome and whether real upstream calls are allowed.

Do not place credentials in files or reusable commands. Use shell environment variables:

export GATEWAY_BASE_URL='https://gateway.example.com/gateway-api'
export GATEWAY_ADMIN_TOKEN='<administrator-jwt>'

Authentication

Management endpoints under /api/admin/* accept administrator user credentials only. A local or server-main sk-* API key is rejected even if it has broad model scopes.

For standalone or hybrid deployments, local login can return a JWT:

curl --fail-with-body \
  -H 'Content-Type: application/json' \
  -d '{"account":"<admin-account>","password":"<admin-password>"}' \
  "$GATEWAY_BASE_URL/api/v1/auth/login"

Do not use local login when the deployment requires OIDC or server-main identity. Obtain the deployment's administrator access token instead.

Verify identity and role before writes:

curl --fail-with-body \
  -H "Authorization: Bearer $GATEWAY_ADMIN_TOKEN" \
  "$GATEWAY_BASE_URL/api/v1/me"

Request Pattern

Use a temporary request file or a carefully quoted inline body without printing secrets:

curl --fail-with-body \
  -H "Authorization: Bearer $GATEWAY_ADMIN_TOKEN" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '<json-body>' \
  "$GATEWAY_BASE_URL/api/admin/<resource>"

Always read current state before PATCH, DELETE, reset, disable, or full replacement. PATCH handlers for providers, base models, pricing rule sets, runtime policy sets, runner policy, and platforms write complete resource shapes rather than merging every omitted field.

High-impact Operations

Obtain explicit confirmation after showing the current snapshot and impact before:

Any DELETE request.
POST /api/admin/catalog/base-models/reset-all.
PUT /api/admin/platforms/{platformID}/models.
Changing a platform status to disabled.
Sending an empty credentials object to clear stored credentials.
Replacing pricing rules or policy contents in a way that removes existing entries.

Full API Fallback

The live machine-readable documents are:

<gateway-api-base-url>/api-docs-json
<gateway-api-base-url>/api-docs-yaml

Use them only when this Skill does not document the required operation. Before acting, confirm the exact path, method, body, authentication, permission, response, and side effect. Do not infer a write operation from a similarly named endpoint.

2.7 KiB Raw Blame History