Open main menu
HomeChrome extensionDeveloper
Get started

How to Use the PDF.ai Delete API

Publish date
Sep 28, 2026
AI summary
The Delete API permanently removes a v2 document, its stored PDF, and cached parse results using a free, zero‑credit POST request with the docId, requiring an API key; it works only for documents created via v2 Parse, Extract, or Split, returns a success flag, and cannot be undone, while non‑v2 documents need the older v1 delete path.
Language
People look up a Delete API when a pipeline has already parsed or split a PDF, and they need to wipe the cached docId, the stored file, and the parse cache from their account. They want a single call that is permanent, free of credit cost, and limited to v2 documents.
This page is the remove a v2 document by docId path on the PDF.ai API v2 Delete endpoint. It does not replace the API Hub (keys and plan live there). It does not re-rank the head term pdf api. It is not the older v1 delete path for documents that were never created by v2 Parse, Extract, or Split. For the first-request path (key + first call), see How to Get Started with the PDF.ai API. For credit math across Parse / Extract / Split / Ask, see How to Understand PDF.ai API Credit Usage.

What Delete is for

After a clean Delete call on PDF.ai API v2, three things should be true:
  • You sent a docId that came from Parse, Extract, or Split
  • The response reports success and confirms the document plus associated data are gone
  • You know Delete costs 0 API credits, and the wipe is permanent
Docs: Delete.
Practical rule: Delete is for cleanup after you are done with a cached docId. Parse, Extract, Split, and Ask are for creating or querying that cache. Use Delete when retention, privacy, or storage cleanup is the next step—not when you still need the document for another call.

What gets removed

From the live Delete docs, a successful call permanently removes:
  • The document record
  • The uploaded PDF file in storage
  • The cached parse results
The docs warn: deletion is permanent and cannot be undone. The endpoint only works for documents created via v2 Parse, Extract, or Split. Other documents need the v1 delete path (the error response points you there).

Credits

From Delete and credit usage:
  • Delete: Free — 0 API credits
API plan examples on credit usage still matter for the calls that created the docId:
  • Free: $0/month for 200 credits/month, no credit card required
  • Paid examples: $49 / 3,000, $99 / 10,000, $249 / 30,000, $599 / 100,000 credits per month
Generate the key and manage the plan on https://pdf.ai/developer. The docs say the key is shown only once when generated.
Practical rule: Delete does not refund Parse / Extract / Split / Ask credits already spent. It only stops the document from sitting in your account afterward.

How to call Delete

1. Have an API key

Open https://pdf.ai/developer, generate a key, store it as a secret. Send it as the X-API-Key header on every call.

2. Keep the docId from Parse, Extract, or Split

Delete requires a docId returned from a prior v2 Parse, Extract, or Split call. If you only have a local file and never parsed it through v2, Delete will not accept that path—you must create the document first, or use the v1 delete flow for non-v2 documents.

3. POST with docId

Endpoint from the docs: POST https://pdf.ai/api/v2/delete
Content type: application/json.
Required:
  • docId — document ID returned from Parse, Extract, or Split
Example shape (Python), matching the docs sample:
import requests

url = "https://pdf.ai/api/v2/delete"
headers = {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}

data = {"docId": "your-document-id"}

response = requests.post(url, headers=headers, json=data)
print(response.json())
A successful response includes success: true and a message that the document and all associated data were deleted successfully.

4. Read the error before you retry

From the Delete docs:
  • Missing docId → docId is required
  • Not a v2 document → error that the document was not created by v2 parse, extract, or split, with a hint to use the v1 delete endpoint
  • Auth problems → fix X-API-Key before you assume the docId is wrong
Practical rule: if Extract or Ask still needs that file, do not Delete yet. Once Delete succeeds, that docId is gone for good.

When Delete is the wrong tool

  • You still need fields, sections, or answers from this file. Use Extract, Split, or Ask with the same docId first (Extract, Split, Ask).
  • You only need searchable text once and will discard the cache afterward. Parse (or Extract/Split with upload), finish the job, then Delete (Parse).
  • The document was never created by v2 Parse / Extract / Split. Use the v1 delete path the docs point to; this endpoint will reject it.
  • You wanted a generic “pdf api” category hub. Stay on https://pdf.ai/developer. This page is the Delete how-to, not a replacement hub.
  • You only need browser cleanup, not API retention control. Account and plan management stay on the developer hub; this page is for programmatic docId cleanup.

A short action plan

  1. Open https://pdf.ai/developer, create a key, store it once.
  1. Finish Parse / Extract / Split / Ask work and keep the docId you intend to retire.
  1. POST https://pdf.ai/api/v2/delete with that docId and confirm success.
  1. Treat the wipe as permanent: do not expect the same docId to work on a later Ask or Extract call.
Sibling guides: How to Get Started with the PDF.ai API, How to Use the PDF.ai Parse API, How to Use the PDF.ai Extract API, How to Use the PDF.ai Split API, How to Use the PDF.ai Ask API, How to Understand PDF.ai API Credit Usage, PDF OCR API: Run OCR from Your Code.
If you want the rest of the PDF workflow after cleanup is clear, start at PDF.ai. Use the Delete API when the next step is retiring a cached docId, not uploading a new file.