Skip to main content
Postcard provides a public REST API for forensic verification of social media posts. You can submit URLs, poll for analysis progress, and retrieve completed forensic reports programmatically.

​
Base URL

https://postcard.fartlabs.org/api/postcards

​
Endpoints at a glance

MethodPathDescription
POST/api/postcardsSubmit a URL for forensic analysis
GET/api/postcards?url=Poll for analysis status and retrieve the completed report
GET/api/postcards/{id}/ogGenerate a dynamic Open Graph image for a completed analysis

Submit URL

Start a forensic analysis for a social media post.

Get postcard status

Poll for analysis progress and retrieve the completed report.

Open Graph image

Generate a dynamic social card image for a completed analysis.

​
Async pattern

The API follows an async request/poll pattern:
  1. Submit — POST /api/postcards returns 202 Accepted immediately with a postcardId. The analysis runs in the background.
  2. Poll — GET /api/postcards?url= returns the current status. Repeat every 3–5 seconds.
  3. Retrieve — When status equals "completed", the full forensic report is in the response body.
The analysis passes through four status states:
StatusDescription
pendingAnalysis queued, not yet started
processingPipeline actively running
completedAnalysis finished; full report available
failedAnalysis could not complete; check the error field

​
CORS

All endpoints include cross-origin resource sharing headers so you can call the API from browser-based clients: 
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Allow-Headers: Content-Type, x-api-key

​
Content type

Send Content-Type: application/json for all POST request bodies. Responses are application/json unless noted otherwise (the OG image endpoint returns image/png).

​
OpenAPI spec and interactive reference

The machine-readable OpenAPI 3.1 specification is available at: 
https://postcard.fartlabs.org/openapi.json
Postcard also provides an interactive API reference powered by Scalar at https://postcard.fartlabs.org/api/reference. You can explore all endpoints, view request/response schemas, and send live requests directly from the browser — no setup required.

Build docs developers (and LLMs) love

Get started for freeTalk to us