# Vietls Public API Boundary

[Developers](https://www.vietls.com/developers)

Controlled beta

## Design rule

Expose stable workflow verbs, not raw internal app routes. Publish a filtered OpenAPI contract only after authentication, request IDs, idempotency, rate limits, and billing semantics are stable.

- [Read the filtered Public OpenAPI v1 contract.](https://www.vietls.com/developers/api/openapi.json)

## Current public API v1 boundary

Approved beta tokens allow no-spend quotes and test jobs. Artifacts are empty and no checkout URL is created. API keys and actual paid execution remain restricted; purchasing a plan does not automatically approve developer access.

Capability discovery is public and read-only. Every other operation listed here requires an approved beta token; web login or a paid subscription alone does not grant developer access.

After beta approval, send `Authorization: Bearer <token>` or `X-Vietls-API-Key: <token>`.

Keep the response `X-Request-ID` and `requestId` for troubleshooting. They identify the request and do not replace the operation’s `idempotencyKey`.

Request example: replace the quote ID with the returned value. Use a unique idempotency key for each new operation and reuse it when retrying that same operation.

- `GET /api/public/v1/capabilities` — Discover the available workflows through this public, read-only endpoint.

- `POST /api/public/v1/quotes` — Request preview-only quotes that spend no credits and create no job.

    ```json
    {
      "workflowId": "prproj.subtitle.extract",
      "units": 1
    }
    ```

- `POST /api/public/v1/jobs` — Use deterministic no-spend dry-run job creation with the returned quote ID, an idempotency key, and explicit quote acceptance and user confirmation. The result has a `job_preview_*` ID.

    ```json
    {
      "workflowId": "prproj.subtitle.extract",
      "quoteId": "quote_preview_01234567",
      "idempotencyKey": "example-job-001",
      "confirmation": {
        "quoteAccepted": true,
        "userConfirmed": true
      }
    }
    ```

- `GET /api/public/v1/jobs/{jobId}` — Poll the returned `job_preview_*` ID and handle `completed_preview` with empty artifacts.

- `GET /api/public/v1/jobs/{jobId}/artifacts` — An empty `artifacts` list is the expected terminal result of a test job.

- `GET /api/public/v1/jobs/{jobId}/artifacts/{artifactId}/download-url` — Request a download URL only after completed live jobs expose artifacts. Test artifacts return `PUBLIC_API_ARTIFACT_NOT_FOUND`.

- `GET /api/public/v1/usage` — Check no-spend accounting: test usage reports zero reserved credits and zero spent credits.

- `POST /api/public/v1/billing/simulations` — Test `scenario: "success"` and `scenario: "provider_failure"` to check reserve, commit, and release with zero ledger mutation. All three confirmation flags must be true.

    ```json
    {
      "workflowId": "prproj.subtitle.extract",
      "quoteId": "quote_preview_01234567",
      "idempotencyKey": "example-simulation-001",
      "scenario": "success",
      "confirmation": {
        "quoteAccepted": true,
        "userConfirmed": true,
        "billingSimulationAccepted": true
      }
    }
    ```

- `POST /api/public/v1/checkout/handoffs` — Validate the hosted checkout handoff after all three user-confirmation flags are true. The preview returns `checkoutUrl: null`, charges nothing, and creates no provider session or subscription.

    ```json
    {
      "planId": "basic",
      "billingCycle": "monthly",
      "idempotencyKey": "example-checkout-001",
      "confirmation": {
        "planReviewed": true,
        "userConfirmed": true,
        "hostedCheckoutAccepted": true
      }
    }
    ```

## Planned public operations

- Enable live hosted checkout URLs only after return-URL allowlisting and first-purchase checks pass.

- Enable artifacts from completed live jobs only after storage, retention, and billing commit/release checks pass.

## Editing workflows to automate

- `prproj.subtitle.extract` — [PRPROJ subtitle extraction](https://www.vietls.com/tools/subtitle-extractor): UI live; API/MCP controlled beta target Use the tool page for manual PRPROJ caption and graphic text inspection; request developer access for automation.

- `prproj.xml.inspect` — [PRPROJ editor XML handoff and repair](https://www.vietls.com/tools/prproj-to-xml): UI live; public workflow wrapper planned Route PRPROJ editor XML handoff, version-marker checks, path repair, and receiving-editor verification preparation to the converter workflow.

- `subtitle.translate` — [Subtitle translation](https://www.vietls.com/tools/ai-subtitle): App workflow live; public quote/job wrapper planned Quote before provider-costed translation and keep extracted file text separate from agent instructions.

- `tts.standard.generate` — [Standard TTS generation](https://www.vietls.com/tools/speech-studio): Managed-provider path in rollout Use quote, reserve, execute, commit/release semantics before exposing paid generation through API or MCP.

- `youtube.transcript.fetch` — [YouTube transcript and media source intake](https://www.vietls.com/tools/youtube-downloader): App workflow live; rights-aware automation boundary required Fetch public metadata or transcripts only within supported source and rights-confirmation policies.

## Error model

Current beta responses include these error codes:

`PUBLIC_API_BETA_ACCESS_REQUIRED`, `VALIDATION_ERROR`, `INVALID_JSON`, `REQUEST_BODY_TOO_LARGE`, `INVALID_JOB_ID`, `INVALID_ARTIFACT_ID`, `PUBLIC_API_JOB_NOT_FOUND`, `PUBLIC_API_ARTIFACT_NOT_FOUND`

The broader public contract also plans these codes; this list does not mean every condition is implemented in the current beta.

`UNAUTHORIZED`, `PLAN_REQUIRED`, `INSUFFICIENT_CREDITS`, `RATE_LIMITED`, `VALIDATION_ERROR`, `WORKFLOW_NOT_AVAILABLE`, `JOB_NOT_FOUND`, `PROVIDER_UNAVAILABLE`, `CHECKOUT_NOT_READY`