# Standard API creation and API-backed resource publication

Complete main-skill preflight and [connections](connections.md) first. For an imported draft, start at step 2 with its `resourceId`; do not create it again.

Follow the [main entry](../SKILL.md) form-first rule for missing API fields and any needed test or publication confirmation.

## 1. Prepare and create

```bash
openany seller schema --type api --application APPLICATION_ID -j
openany seller apis create --application APPLICATION_ID --file api.json --operation TASK-api-create-1 -j
```

Prepare `api.json` against the current schema with an owned `connectionId`, `name`, `description`, `method`, `pathTemplate`, `requestContentType`, and `config`. Use the actual billing terms, inputs, request mappings, and charge conditions; ask for missing information. Amounts such as `price_micro_usd` are strings in micro-USD, not USD floating point. Do not put authentication headers or secrets in the configuration. Record the returned `id` as `API_ID`.

### Resource categories

Before creating or listing a new API, collect `categories` through the native form if the user has not supplied them. Use the website's current API category IDs and labels (the API import template's category `allowedValues`), with at most 16 unique IDs. Put the selection in top-level `categories`, not in `config` and not in supplier application `resource.primary_category`. Do not silently use `other`, an empty array, or a supplier category as a resource category. Preserve existing categories on edits; do not force a new selection for an unchanged resource. If current options are unavailable, report the missing options and ask for a console selection rather than inventing IDs. The API schema's generic string array alone is not a category catalog.

## 2. Use the saved configuration

Use the creation or import receipt to confirm the draft ID. If the user requested only a draft, report its ID and stop. For verification, reuse the saved `id`, `revision`, `connectionId`, and `connectionRevision` from the receipt. Fetch the API once if the receipt is missing fields needed for the current step.

```bash
openany seller apis get --application APPLICATION_ID --id API_ID -j
```

## 3. Verify

Reuse a verification receipt only if `state` is `"passed"`, `stale` is `false`, and its `apiId`, `apiRevision`, `connectionId`, and `connectionRevision` match the saved API's `id`, `revision`, `connectionId`, and `connectionRevision`. This check determines whether a receipt verifies the current configuration. For publication eligibility, also check the historical verification rules below. Reconcile any running or uncertain verification first. Start one verification only if it is needed and the test request and cost limits are authorized.

Prepare `verification.json` with `expectedRevision` from the saved API `revision`, `expectedConnectionRevision` from its `connectionRevision`, and `request` containing the authorized path/query/headers/body as applicable. The stored connection supplies credentials; never embed them in the request.

```bash
openany seller apis verify --application APPLICATION_ID --id API_ID --file verification.json --operation TASK-api-test-1 -j
```

Use a complete synchronous passing receipt directly once it meets the checks above. If asynchronous verification returns `running`, record its `id` and query that verification after about 10–15 seconds. Use bounded backoff until the task deadline. If it is still running at the deadline, report it as pending with its ID and preserve the original verification. Follow [recovery](reviews.md) for failed, unknown, or expired results.

```bash
openany seller apis get --application APPLICATION_ID --id API_ID --verification-id VERIFICATION_ID -j
```

## 4. Publish

Publish only if the supplier is `live` and publication is authorized. Set `expectedRevision` and `expectedConnectionRevision` to the current saved API and connection revisions. For first publication or asynchronous publication, the server requires a successful verification for this API. Reuse a matching passing receipt or the API's saved `passedVerificationId` if the server reports one. When reusing a historical pass, use current revisions in the publication request. A previously published synchronous API can be republished without a new verification when its current configuration satisfies server checks. Include `verificationId` when using a receipt. Individual resources do not need a separate review submission.

```bash
openany seller apis publish --application APPLICATION_ID --id API_ID --file publication.json --operation TASK-api-publish-1 -j
```

Report publication and runtime synchronization separately. If publication succeeds, report the result and stop. If runtime synchronization is pending, continue waiting only if the user asked to wait until the API is available. Fetch the API by ID only if the publication result is uncertain. Follow [recovery](reviews.md) for missing verification or revision conflicts before retrying. For unpublication, use `unpublish` with `expectedRevision`.

## Correct a resource

Read the resource and prepare a schema-valid configuration using the current version and connection revisions. No review withdrawal is required. For an authorized edit:

```bash
openany seller apis update --application APPLICATION_ID --id API_ID --file api-update.json --operation TASK-api-update-2 -j
```

Read back and reverify changed configuration as required. Reconcile uncertain writes before any further mutation.
