skills/ycloud-whatsapp-media/references/openapi.md

<!-- Generated by scripts/build_openapi_skill_references.py; do not edit. -->
# OpenAPI contract: WhatsApp media

## Provenance

- Source: `ycloud-api-v2.yaml` (pinned release snapshot).
- Source SHA-256: `8592bd4cc37186655a480dd86ce6bac6731543727327a2871d9103a0b8ed9e81`
- OpenAPI version: `3.0.0`
- API info.version: `v2`
- This derived reference does not replace the upstream API Owner's canonical source.
- Generated deterministically from normalized JSON; do not edit this file by hand.

## Scope and handoff

- Upload returns a media ID for a later message request. Uploading media does not send a message; hand off the media ID to Messages. This MVP does not read or upload a real local file.
- Operation coverage: `1`

## Operations

### `POST /whatsapp/media/{phoneNumber}/upload` — `whatsapp_media-upload`

- Summary: Upload media
- Description:
  > Uploads media that can later be sent in WhatsApp messages. This endpoint interfaces with Meta's WhatsApp Business API media endpoints. All media files sent through this endpoint are encrypted and persist for 30 days.
  >
  > For supported media types and size limitations, please refer to [Supported Media Types](https://developers.facebook.com/docs/whatsapp/cloud-api/reference/media#supported-media-types).
  >
  > For more information, refer to [Meta's WhatsApp Cloud API Media documentation](https://developers.facebook.com/docs/whatsapp/cloud-api/reference/media).
  >
  > Note that all interactive messages cannot send images, documents, videos, or audio using a Media ID in the header section. These elements must be sent using a link.
- Parameters:
  - `phoneNumber` (path, required): `string`
    > Phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format to use for the upload.
    - Constraints: example="+16315551111"
- Request body: required
  - `multipart/form-data`: `object`
    - Required properties: `file`
    - Properties:
      - `file`: `string (binary)` (required)
        - Description:
          > The media file to upload. Only one file is supported. If multiple files are uploaded, only the first file will be processed.
- Responses:
  - `200`: Successfully uploaded the media.
    - `application/json`: `object`
      - Properties:
        - `id`: `string`
          - Description:
            > The ID of the uploaded media that can be used in subsequent message requests.
  - `400`: Bad request. The file may be invalid or exceed size limits.
    - `application/json`: `#/components/schemas/ErrorResponse`
      - `$ref`: `#/components/schemas/ErrorResponse`
  - `404`: The requested resource does not exist.
    - `application/json`: `#/components/schemas/ErrorResponse`
      - `$ref`: `#/components/schemas/ErrorResponse`

## Referenced schema and parameter shapes

### `Error`

- Reference: `#/components/schemas/Error`
- Shape: `object`
  - Required properties: `status`, `code`
  - Properties:
    - `code`: `string` (required)
      - Description:
        > One of a server-defined error codes. Some `4xx` errors that could be handled programmatically include an error code that briefly explains the error reported.
      - Constraints: example="NOT_FOUND"
    - `docUrl`: `string`
      - Description:
        > A URL to more information about the error.
      - Constraints: example=""
    - `message`: `string`
      - Description:
        > A human-readable representation of the error. It is intended as an aid to developers and is not suitable for exposure to end users.
      - Constraints: example="The requested resource does not exist."
    - `requestId`: `string`
      - Description:
        > Each API request has an associated request ID. It conveys the response header `YCloud-Request-ID` used for the convenience of the consumer.
      - Constraints: example="req_1KjtKI80IKoaJNa6n6p"
    - `status`: `integer (int32)` (required)
      - Description:
        > HTTP status code, [RFC 7231, Section 6](https://datatracker.ietf.org/doc/html/rfc7231#section-6). It conveys the HTTP status code used for the convenience of the consumer.
      - Constraints: pattern="[45]\\d{2}"; example=404
    - `target`: `string`
      - Description:
        > The target of the error.
      - Constraints: example=""
    - `whatsappApiError`: `#/components/schemas/WhatsappApiError`
      - Description:
        > The original error object returned by WhatsApp. See [Handling Errors](https://developers.facebook.com/docs/graph-api/guides/error-handling), [Cloud API Error Codes](https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes).
        >
        > Note: This field is returned if we tried to request the WhatsApp Business API and got an error response.

### `ErrorResponse`

- Reference: `#/components/schemas/ErrorResponse`
- Shape: `object`
  - Required properties: `error`
  - Properties:
    - `error`: `#/components/schemas/Error` (required)

### `WhatsappApiError`

- Reference: `#/components/schemas/WhatsappApiError`
- Shape: `object`
  - Description:
    > The original error object returned by WhatsApp. See [Handling Errors](https://developers.facebook.com/docs/graph-api/guides/error-handling), [Cloud API Error Codes](https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes).
  - Required properties: `message`, `code`
  - Properties:
    - `code`: `string` (required)
      - Description:
        > An error code.
      - Constraints: example=200002
    - `error_data`: `object`
      - Description:
        > Additional data about the error. A string or map.
        > - For template APIs, this field is a string describing the reason for the error.
        > - For message APIs, this field is a map with property `details` describing the reason for the error.
    - `error_subcode`: `string`
      - Description:
        > Additional code about the error.
      - Constraints: example=2388109
    - `error_user_msg`: `string`
      - Description:
        > The message to display to the user. The language of the message is based on the locale of the API request.
      - Constraints: example="This message template cannot be created."
    - `error_user_title`: `string`
      - Description:
        > The title of the dialog, if shown. The language of the message is based on the locale of the API request.
      - Constraints: example="Message Cannot Be Submitted"
    - `fbtrace_id`: `string`
      - Description:
        > Internal support identifier. When reporting a bug related to a Graph API call, include the fbtrace_id to help us find log data for debugging.
      - Constraints: example="AVGjJ7ia2zJkrHG"
    - `is_transient`: `boolean`
      - Description:
        > Whether the error is transient.
      - Constraints: example=false
    - `message`: `string` (required)
      - Description:
        > A human-readable description of the error.
      - Constraints: example="HSM Template creation failed"
    - `type`: `string`
      - Description:
        > Error type.
      - Constraints: example="OAuthException"

## Codegen interpretation and unknowns

- `operationId` identifies the OpenAPI operation; it is not an SDK method name.
- `allOf` is wire-level schema composition. Response adapters must merge inherited and local properties; generated model inheritance/flattening is only a codegen shape, not additional API behavior.
- `x-group-parameters`, `x-enum-varnames`, and `x-enum-descriptions` are generator hints, not business rules.
- Description-only constraints (including conditional fields, precedence, and endpoint-specific behavior) remain verbatim above.
- This OpenAPI snapshot does not confirm cross-cutting error, retry/`Retry-After`, rate-limit, idempotency, delivery, or webhook-signature behavior. Consult the reviewed `runtime.md`; if neither source confirms a fact, do not fill it in.