Skip to main content
DELETE
/
v1
/
characters
/
{id}
Delete a character
curl --request DELETE \
  --url https://api.aurous-labs.com/v1/characters/{id} \
  --header 'X-Api-Key: <api-key>'
{
  "id": "char_01HXMQ7Z3K8Y2NABCDEFGHJKMR",
  "object": "character",
  "deleted": true
}
DELETE /v1/characters/{id} removes a character. The branching is automatic, based on status:
  • reviewing → hard-delete (cancel-review). The 4 generated refs are discarded, the row is removed entirely. Subsequent retrieval returns 404. Use this when synthesis produced refs you don’t want to keep.
  • Any other status (ready, failed, synthesizing, deleted) → soft-delete. Sets deleted_at, transitions status to deleted. The row remains for ID stability (you can still GET /v1/characters/{id} for audit), but it is excluded from GET /v1/characters and rejected by POST /v1/images.
This endpoint never charges credits and does not refund credits already spent on synthesis.

​
When to use

  • Cancel-review: the synthesize flow produced refs you reject; you want the character gone, not archived.
  • Soft-delete ready: retire a character you no longer plan to use. Past generations that already reference it on GET /v1/images/{id} are unaffected, but the character can no longer be attached to new requests.
  • Soft-delete failed: clean up failed synthesis attempts you don’t intend to retry via resynthesize.

​
Examples

curl -X DELETE https://api.aurous-labs.com/v1/characters/char_01HXMQ7Z3K8Y2ABCDEFGHJKM \
  -H "X-Api-Key: $AUROUS_API_KEY"

​
Limits

  • Rate limit: bucket characters_post — 30 requests/min sustained, 60 burst per team.

​
Errors

CodeHTTPWhen
resource_not_found404Unknown ID or cross-team. The 404 is intentional — cross-team existence is never leaked.

​
Common pitfalls

  • A reviewing character is hard-deleted — the row vanishes. Subsequent GET /v1/characters/{id} returns 404. If you cared about the refs, call POST /v1/characters/{id}/save first.
  • Soft-deleting a ready character does not affect generations you already produced — their output_urls continue to work and the character ID still appears on past GET /v1/images/{id} responses.
  • Calling DELETE a second time on the same character returns 404, since soft-deleted rows are filtered out for IDOR safety. Treat the first 200 as the only success signal you need.

Authorizations

​
X-Api-Key
string
header
required

Your team API key (starts with al_live_).

Headers

​
Aurous-Version
string

Optional API version pin (YYYY-MM-DD). Defaults to your team's pinned version, or the system default 2026-05-15 for unauthenticated requests.

Pattern: ^\d{4}-\d{2}-\d{2}$
Example:

"2026-05-15"

Path Parameters

​
id
string
required

Opaque character ID

Example:

"char_01HXMQ7Z3K8Y2NABCDEFGHJKMR"

Response

Character deleted

​
id
string
required

Character ID echoed back.

Example:

"char_01HXMQ7Z3K8Y2NABCDEFGHJKMR"

​
object
enum<string>
required

Discriminator

Available options:
character
Example:

"character"

​
deleted
boolean
required

Always true on a successful delete.

Example:

true