> ## 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 Character
> Delete a Cinematic character for good
## Overview
Deletes one of your team's characters, the same as **Delete** in **Studio → Characters**.
**This cannot be undone.** [Get Character](/api-reference/character/details) answers `404` for it from then on, and it leaves [List Characters](/api-reference/character/list).
As in the dashboard, deleting is never refused:
* Cinematic projects that cast the character keep their own copy of the cast, so they keep working. `projectsUsing` says how many there are (the number the dashboard warns with).
* Its photos stay in your [media library](/api-reference/media/list). Delete them with [Delete Media](/api-reference/media/delete) if you no longer need them.
* A portrait still being generated finishes into your library and its credits are not given back.
```bash cURL theme={null}
curl -X DELETE "https://api.hooked.so/v1/character/cm4xa1b2c0001cd34ef56gh78" \
-H "x-api-key: your_api_key_here"
```
```javascript JavaScript theme={null}
const response = await fetch("https://api.hooked.so/v1/character/cm4xa1b2c0001cd34ef56gh78", {
method: "DELETE",
headers: { "x-api-key": process.env.HOOKED_API_KEY },
});
const { data } = await response.json();
```
```python Python theme={null}
import os
import requests
response = requests.delete(
"https://api.hooked.so/v1/character/cm4xa1b2c0001cd34ef56gh78",
headers={"x-api-key": os.environ["HOOKED_API_KEY"]},
)
data = response.json()["data"]
```
```json 200 theme={null}
{
"success": true,
"message": "Character deleted",
"data": {
"characterId": "cm4xa1b2c0001cd34ef56gh78",
"deleted": true,
"projectsUsing": 2
}
}
```
```json 404 theme={null}
{
"success": false,
"message": "Character 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 character in your team, including one already deleted. Another team's character, or an id that is not one, answers the same `Character not found` |
## OpenAPI
````yaml DELETE /v1/character/{characterId}
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/character/{characterId}:
delete:
tags: []
summary: Delete Character
description: >-
Deletes a character for good, like Studio → Characters. **This cannot be
undone.** It is never refused: Cinematic projects that cast it keep
their own copy of the cast. `projectsUsing` is how many Cinematic
projects cast it (the number the dashboard warns with). Its photos stay
in your media library.
operationId: deleteCharacter
parameters:
- name: characterId
in: path
required: true
schema:
type: string
description: The character id, from List Characters.
responses:
'200':
description: Character deleted
content:
application/json:
schema:
type: object
required:
- success
- data
properties:
success:
type: boolean
message:
type: string
data:
type: object
required:
- characterId
- deleted
- projectsUsing
properties:
characterId:
type: string
description: The character that was deleted
deleted:
type: boolean
description: Always `true`
projectsUsing:
type: integer
description: >-
Cinematic projects that had cast it. They keep
working.
example:
success: true
message: Character deleted
data:
characterId: cm4xa1b2c0001cd34ef56gh78
deleted: true
projectsUsing: 2
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/EntitlementRequired'
'404':
description: >-
No such character in your team (another team's or a malformed id
answers the same)
content:
application/json:
schema:
$ref: '#/components/schemas/NotFound404'
example:
success: false
message: Character not found
'429':
$ref: '#/components/responses/RateLimited429'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/Error500'
example:
success: false
message: Internal server error
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
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
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
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
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.