> ## Documentation Index > Fetch the complete documentation index at: https://docs.roughy.ai/llms.txt > Use this file to discover all available pages before exploring further. # List cuts > Paginated list of your cuts, newest first. ## OpenAPI ````yaml https://roughy-api-staging.fly.dev/v1/openapi.json get /v1/cuts openapi: 3.1.0 info: title: Roughy Public API version: 0.0.0 servers: - url: https://roughy-api-staging.fly.dev description: Staging security: [] tags: - name: Projects description: >- Workflow containers. Every asset lives inside a project; a project groups everything for one piece of work (an episode, an interview, a talk). - name: Assets description: >- The unit of media. `POST /assets` creates one and opens its upload in a single call: the response body is the asset (its `upload_url` carries the transfer URL while `pending_upload`), and the TUS transfer URL also comes back in the `Location` header. List, detail (with signed download URL), and delete round it out. Each asset belongs to exactly one project; `language` is set at create and immutable. - name: Uploads description: >- Drive the TUS-resumable transfer that streams an asset's bytes. `POST /assets` opens the upload; `PATCH`/`HEAD` move and resume the bytes, `DELETE` cancels (removing the asset). Lost the transfer URL? Re-`GET` the asset — while it's `pending_upload`, `upload_url` carries it. - name: Cuts description: >- A kept-segment plan for an asset, computed automatically by Roughy. Create one with `POST /cuts {asset_id, script?}`, list with `GET /cuts`, read a cut, export it to NLE formats, and export its generated subtitle (SRT / VTT). - name: Renders description: >- Renders an asset to a video (`mp4`/`mov`) or audio (`m4a`/`mp3`) output, optionally applying a `cut_id`. `POST /renders {asset_id, cut_id?, output}` creates one; list, read (with a signed download URL), and cancel as a top-level `/renders` resource. - name: Webhooks description: >- Register endpoints to receive signed terminal-state events (cut / render / asset) instead of polling. - name: Credits description: Credit balance and usage history. - name: Users description: Your account and profile. - name: OAuth description: >- Device authorization grant (RFC 8628), served at app.roughy.ai/oauth/* for the editor plugin. Internal surface — not part of the public /v1 SDK. - name: billing description: Stripe customer portal, invoices, subscriptions. - name: api-keys description: Mint and revoke API keys. - name: auth description: Sign up, log in, log out, and OAuth flows for the dashboard. - name: webhooks description: Inbound provider webhooks (Stripe, Resend, ElevenLabs). - name: email-preferences description: Per-category transactional-email opt-out preferences. - name: sse description: Server-sent live updates per asset. - name: health description: Liveness and readiness probes. paths: /v1/cuts: get: tags: - Cuts summary: List cuts description: Paginated list of your cuts, newest first. operationId: list_cuts_v1_cuts_get parameters: - name: asset_id in: query required: false schema: anyOf: - type: string format: uuid - type: 'null' description: Restrict to one asset's cuts (1:N, newest first). title: Asset Id description: Restrict to one asset's cuts (1:N, newest first). - name: project_id in: query required: false schema: anyOf: - type: string format: uuid - type: 'null' description: Restrict to one project. title: Project Id description: Restrict to one project. - name: state in: query required: false schema: anyOf: - $ref: '#/components/schemas/PublicCutState' - type: 'null' description: Filter by lifecycle state. title: State description: Filter by lifecycle state. - name: limit in: query required: false schema: type: integer maximum: 100 minimum: 1 description: Maximum cuts to return (1-100). Default 20. default: 20 title: Limit description: Maximum cuts to return (1-100). Default 20. - name: offset in: query required: false schema: type: integer minimum: 0 description: Cuts to skip from the start. Default 0. default: 0 title: Offset description: Cuts to skip from the start. Default 0. responses: '200': description: One page of your cuts, newest first. content: application/json: schema: $ref: '#/components/schemas/CutListResponse' '404': description: Asset or project not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: not_found message: Asset or project not found. security: - HTTPBearer: [] components: schemas: PublicCutState: type: string enum: - pending - processing - completed - failed title: PublicCutState description: |- Cut states reachable on the public API surface: a cut computes `pending` → `processing` and lands `completed`, or `failed`. CutListResponse: properties: items: items: $ref: '#/components/schemas/CutResponse' type: array title: Items description: Page of cuts, newest first. total: type: integer title: Total description: >- Total cuts matching the filter across all pages — not the size of `items`. limit: type: integer title: Limit description: The `limit` echoed back from the request. offset: type: integer title: Offset description: The `offset` echoed back from the request. type: object required: - items - total - limit - offset title: CutListResponse description: Paginated list of the caller's cuts, newest first. ErrorResponse: properties: error: $ref: '#/components/schemas/ErrorBody' type: object required: - error title: ErrorResponse description: |- The shape every error response returns. Request-correlation lives in the `X-Request-Id` response header — include that header value in a support ticket to correlate with server-side logs. example: error: code: validation_error fields: - field: body.name message: Field required message: Upload-Length must be at least 64 bytes. CutResponse: properties: id: type: string format: uuid title: Id description: Cut id. asset_id: type: string format: uuid title: Asset Id description: The source asset (video or audio) this cut belongs to. state: $ref: '#/components/schemas/PublicCutState' description: >- Cut lifecycle state: `pending` / `processing` while the cut computes, `completed` when ready, `failed` on error. `completed` and `failed` are terminal. script: anyOf: - type: string - type: 'null' title: Script description: >- The script this cut was computed with (from the create request, snapshotted at create time). error_code: anyOf: - type: string - type: 'null' title: Error Code description: Machine-readable failure code when `state=failed`. error_message: anyOf: - type: string - type: 'null' title: Error Message description: Human-readable failure detail when `state=failed`. created_at: type: string format: date-time title: Created At description: When the cut was created. started_at: anyOf: - type: string format: date-time - type: 'null' title: Started At description: When compute started. completed_at: anyOf: - type: string format: date-time - type: 'null' title: Completed At description: When the cut reached a terminal state. type: object required: - id - asset_id - state - script - error_code - error_message - created_at - started_at - completed_at title: CutResponse description: A cut. ErrorBody: properties: code: $ref: '#/components/schemas/ErrorCode' description: >- Stable enum classifier. Clients should switch on this to drive retry / display logic; `message` is for humans. message: type: string title: Message description: >- One-line human-readable description of the failure. Safe to show end users; never carries backend internals. fields: anyOf: - items: $ref: '#/components/schemas/ErrorFieldDetail' type: array - type: 'null' title: Fields description: >- Per-field validation errors, set only for `code: validation_error` responses. Omitted in every other case. type: object required: - code - message title: ErrorBody description: Inner `error` object — the body of `ErrorResponse.error`. ErrorCode: type: string enum: - bad_request - unauthenticated - forbidden - not_found - conflict - gone - precondition_failed - payload_too_large - unsupported_media_type - validation_error - account_locked - rate_limited - insufficient_credits - internal_error - upstream_error - upstream_unavailable - asset_processing - asset_payment_required - asset_failed - asset_not_ready - modifier_not_ready - unsupported_format - frame_rate_required - cut_not_proposed title: ErrorCode description: |- Stable, client-facing error-classifier enum. New entries require an ADR amendment so SDK consumers can rely on the list being closed. Numeric HTTP status code stays in the response status line — `code` is the orthogonal *category* clients switch on without parsing the message. ErrorFieldDetail: properties: field: type: string title: Field description: >- Dotted path to the offending field, rooted at the request location (e.g. `body.name`, `query.limit`, `path.project_id`). message: type: string title: Message description: Human-readable explanation for this field. type: object required: - field - message title: ErrorFieldDetail description: Per-field validation failure on a single request field. securitySchemes: HTTPBearer: type: http description: >- Pass your API key as `Authorization: Bearer sk_…`. Mint a key from your dashboard's API-keys page. scheme: bearer bearerFormat: sk_… ````