> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hooked.so/llms.txt
> Use this file to discover all available pages before exploring further.
# Delete Video
> Delete a rendered video for good
## Overview
Deletes one rendered video.
**This cannot be undone.** The video, its file and its thumbnail are deleted. Download the file first if you want to keep it.
What happens:
* The video is deleted. [Get Video Details](/api-reference/video/details) answers `404` for it from then on.
* Its project stays. [Get Project](/api-reference/project/details) then shows the project's previous render, or `video: null` if there is none; render it again with [Render Project](/api-reference/video/render).
* Posts already recorded for the video are deleted from Hooked. A video already published stays on the platform.
* The storage the file used is given back to your team.
To delete the project as well, use [Delete Project](/api-reference/project/delete), which deletes all its videos.
## When it is refused
Nothing is deleted and the answer is `409` while:
| `message` | What to do |
| - | - |
| `Video is still rendering` | Wait until its `status` is `COMPLETED` or `FAILED`. |
| `Video has a pending scheduled post…` | Cancel each post in `data.scheduleIds` with [Cancel Scheduled Post](/api-reference/schedule/delete), then delete again. |
```bash cURL theme={null}
curl -X DELETE "https://api.hooked.so/v1/video/cm4x9n7q20003ab12xy98zt10" \
-H "x-api-key: your_api_key_here"
```
```javascript JavaScript theme={null}
const videoId = "cm4x9n7q20003ab12xy98zt10";
const response = await fetch(`https://api.hooked.so/v1/video/${videoId}`, {
method: "DELETE",
headers: { "x-api-key": process.env.HOOKED_API_KEY },
});
const result = await response.json();
console.log(response.status, result.message);
```
```python Python theme={null}
import os
import requests
video_id = "cm4x9n7q20003ab12xy98zt10"
response = requests.delete(
f"https://api.hooked.so/v1/video/{video_id}",
headers={"x-api-key": os.environ["HOOKED_API_KEY"]},
)
print(response.status_code, response.json()["message"])
```
```json 200 theme={null}
{
"success": true,
"message": "Video deleted",
"data": {
"videoId": "cm4x9n7q20003ab12xy98zt10",
"deleted": true
}
}
```
```json 409 theme={null}
{
"success": false,
"message": "Video is still rendering"
}
```
```json 404 theme={null}
{
"success": false,
"message": "Video not found"
}
```
## Errors
| Status | When |
| - | - |
| 401 | Missing or invalid API key (`code: "not_authenticated"`) |
| 403 | The team does not have the Hooked app product (`code: "entitlement_required"`) |
| 404 | No such video, including one already deleted. Another team's video, or an id that is not one, answers the same `Video not found` |
| 409 | The video is rendering, or it has a pending scheduled post. Nothing was deleted |
| 500 | `Internal server error`. Read the video before retrying: it may already be gone |
## OpenAPI
````yaml DELETE /v1/video/{videoId}
openapi: 3.0.0
info:
title: Hooked API
version: 1.0.0
description: AI Video Generation API
servers:
- url: https://api.hooked.so
security:
- ApiKeyAuth: []
tags:
- name: Videos
description: Create projects, follow them and render videos
- name: Account Analysis
description: Analyze TikTok and YouTube accounts
- name: Channels
description: Connected social accounts you publish to
- name: Publish
description: Schedule videos to your connected accounts
- name: Images
description: 'Image editing: background removal and expansion'
- name: Media
description: 'Your media library: list, import from a URL, upload a file'
- name: Avatars
description: Your team's own avatars (Actors) and their Hook + Demo reactions
paths:
/v1/video/{videoId}:
delete:
tags: []
summary: Delete Video
description: >-
Deletes a rendered video for good. **This cannot be undone.** The video
row, its file and thumbnail and any post already recorded for it are
removed, and the storage it used is freed. Its project stays: render it
again with POST /v1/render. Refused with 409 while the video is
rendering (`STARTED`) or while it has a pending scheduled post (cancel
it first with DELETE /v1/schedule/{scheduleId}).
operationId: deleteVideo
parameters:
- name: videoId
in: path
required: true
schema:
type: string
description: >-
The video ID: `data.video.id` from GET /v1/project/{projectId}, an
item of GET /v1/video/list, `data.videoId` from POST /v1/render, or
`data.videoId` in a webhook payload.
example: cm4x9n7q20003ab12xy98zt10
responses:
'200':
description: Video deleted
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
message:
type: string
data:
type: object
required:
- videoId
- deleted
properties:
videoId:
type: string
description: The video that was deleted
deleted:
type: boolean
description: Always `true`
example:
success: true
message: Video deleted
data:
videoId: cm4x9n7q20003ab12xy98zt10
deleted: true
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/EntitlementRequired'
'404':
description: >-
No such video, including one already deleted. Another team's video,
or an id that is not one, answers the same way.
content:
application/json:
schema:
$ref: '#/components/schemas/NotFound404'
example:
success: false
message: Video not found
'409':
description: The video cannot be deleted yet; nothing was deleted
content:
application/json:
schema:
$ref: '#/components/schemas/Conflict409'
examples:
rendering:
value:
success: false
message: Video is still rendering
scheduled:
value:
success: false
message: >-
Video has a pending scheduled post. Cancel it first with
DELETE /v1/schedule/{scheduleId}
data:
scheduleIds:
- clxsched0001
'429':
$ref: '#/components/responses/RateLimited429'
'500':
$ref: '#/components/responses/InternalError'
security:
- ApiKeyAuth: []
components:
responses:
Unauthorized:
description: Missing or invalid API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error401'
EntitlementRequired:
description: The team does not have the product this endpoint needs
content:
application/json:
schema:
$ref: '#/components/schemas/EntitlementRequired403'
RateLimited429:
description: >-
Your team is over a rate limit: 30 POST requests per minute, 120 other
requests per minute, or 3 downloads of your URLs running at once.
Nothing ran and nothing was charged: wait `Retry-After` seconds and send
the request again. See [Rate
limits](/guides/error-handling#rate-limits-429).
headers:
Retry-After:
description: Seconds to wait before sending again.
schema:
type: integer
X-RateLimit-Limit:
description: The limit of the bucket you hit (not sent for the download cap).
schema:
type: integer
X-RateLimit-Remaining:
description: 'Requests left in this window: 0 (not sent for the download cap).'
schema:
type: integer
X-RateLimit-Reset:
description: >-
When the window ends, in Unix seconds (not sent for the download
cap).
schema:
type: integer
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
enum:
- false
errorCode:
type: string
enum:
- RATE_LIMITED
message:
type: string
retryAfterSeconds:
type: integer
required:
- success
- errorCode
- message
- retryAfterSeconds
example:
success: false
errorCode: RATE_LIMITED
message: >-
Rate limit exceeded: 30 POST requests per minute per team. Retry
after 12 s.
retryAfterSeconds: 12
InternalError:
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/Error500'
schemas:
NotFound404:
type: object
description: >-
Not found. Another team's resource answers the same way as a missing
one.
properties:
success:
type: boolean
enum:
- false
message:
type: string
required:
- success
- message
example:
success: false
message: Project not found
Conflict409:
type: object
description: >-
The resource cannot be deleted right now. `message` says why; nothing
was deleted.
properties:
success:
type: boolean
enum:
- false
message:
type: string
data:
type: object
properties:
scheduleIds:
type: array
items:
type: string
description: >-
The pending scheduled posts in the way. Cancel each with DELETE
/v1/schedule/{scheduleId}, then retry.
required:
- success
- message
Error401:
type: object
description: Missing or invalid `x-api-key`.
properties:
code:
type: string
enum:
- not_authenticated
message:
type: string
example: Not authenticated
errorCode:
type: string
enum:
- NOT_AUTHENTICATED
details:
type: object
additionalProperties:
type: string
example:
code: not_authenticated
message: Not authenticated
errorCode: NOT_AUTHENTICATED
details:
x-api-key: Header not provided or API Key invalid
EntitlementRequired403:
type: object
description: >-
Valid key, but the team does not have the product this endpoint belongs
to.
properties:
code:
type: string
enum:
- entitlement_required
error:
type: string
enum:
- entitlement_required
message:
type: string
product:
type: string
example: app
required:
- code
- error
- message
- product
example:
code: entitlement_required
error: entitlement_required
message: This endpoint requires the "app" product.
product: app
Error500:
type: object
properties:
success:
type: boolean
enum:
- false
message:
type: string
error:
type: string
description: Present on some endpoints
example:
success: false
message: Internal server error
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.