Skip to content

Delete a post

DELETE
/posts/{id}

Soft-deletes a post: it leaves feeds, lookups and its own page, but its record, members and tags are kept and it can be restored. The author may delete it, and so may holders of posts.admin or system.admin and holders of posts.admin for the post’s team. A post that is missing or already deleted is 404. The member assets and their files aren’t touched.

An optional reason is stored with the deletion; it is trimmed and may be at most 500 bytes long. The deletion and its federation activity are written together, also for drafts, and an audit entry is recorded afterwards on a best-effort basis. Deleted posts are removed for good by a background job once they are older than the retention period, 30 days by default.

id
required
string format: uuid

The post’s id.

Optional body for a delete. Send nothing, or {}, to delete without a reason.

object
reason

Why it was deleted, stored as deleted_reason. Surrounding spaces are trimmed, an empty reason counts as none, and more than 500 bytes after trimming gets 400.

string
<= 500 characters

The post was deleted.

Malformed request

object
error
required

Human-readable error summary

string
Example
the request could not be completed

Authentication required, missing, or invalid

object
error
required

Human-readable error summary

string
Example
the request could not be completed
Example
{
"error": "authentication required: sign in and retry with a valid session or API token"
}

Authenticated but missing required capabilities

object
error
required

Human-readable error summary

string
Example
the request could not be completed

Resource not found

object
error
required

Human-readable error summary

string
Example
the request could not be completed