# API Discovery and Safety

## Required Inputs

- Gateway origin and public API base URL. Public API access always ends with `/api/v1`; direct local access commonly uses `http://127.0.0.1:8088/api/v1`.
- 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:

```bash
export GATEWAY_ORIGIN='https://gateway.example.com'
export GATEWAY_PUBLIC_API_BASE="$GATEWAY_ORIGIN/api/v1"
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:

```bash
curl --fail-with-body \
  -H 'Content-Type: application/json' \
  -d '{"account":"<admin-account>","password":"<admin-password>"}' \
  "$GATEWAY_PUBLIC_API_BASE/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:

```bash
curl --fail-with-body \
  -H "Authorization: Bearer $GATEWAY_ADMIN_TOKEN" \
  "$GATEWAY_PUBLIC_API_BASE/me"
```

## Request Pattern

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

```bash
curl --fail-with-body \
  -H "Authorization: Bearer $GATEWAY_ADMIN_TOKEN" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '<json-body>' \
  "$GATEWAY_ORIGIN/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-origin>/api/v1/openapi.json`
- `<gateway-origin>/api/v1/openapi.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.