POSTARD DEVELOPERS

API quickstart

Find your workspace, then send it a draft. These examples use the existing app-session authentication, not a customer API key.

1. Prepare your development session

Use a configured Postard development instance with Supabase and the API running. Sign in and create a workspace in the web app. You need an owner, admin, or editor role to save drafts.

In your own first-party integration, obtain the session through the configured Supabase client. The publishable key identifies the project; it does not replace a user access token.

const { data: { session } } = await supabase.auth.getSession();
if (!session) throw new Error("Sign in first.");

const response = await fetch(
  apiOrigin + "/v1/workspaces",
  { headers: { Authorization: "Bearer " + session.access_token } },
);
if (!response.ok) throw new Error("Postard returned " + response.status);
const { data: workspaces } = await response.json();

This reads an existing session for an outgoing request. The API independently verifies the token. Let Supabase manage refresh in your app; do not embed a user token in source code, public pages, logs, or an AI prompt.

2. List your workspaces

For the shell examples, set POSTARD_API_URL to the configured API origin and ACCESS_TOKEN to a short-lived app-session token in your local environment. Keep credentials out of shared shell history. Local development uses http://localhost:4000.

curl "$POSTARD_API_URL/v1/workspaces" \
  --header "Authorization: Bearer $ACCESS_TOKEN"

{
  "data": [{
    "id": "11111111-1111-4111-8111-111111111111",
    "name": "My brand",
    "created_at": "2026-11-04T10:00:00Z"
  }]
}

Use an ID from your actual response as WORKSPACE_ID. An empty array means this user has no accessible workspaces; create one in the web app.

3. Save a draft

curl --request POST \
  "$POSTARD_API_URL/v1/workspaces/$WORKSPACE_ID/drafts" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"title":"A fresh perspective","content":"Something worth sharing starts here."}'

{
  "data": {
    "id": "22222222-2222-4222-8222-222222222222",
    "title": "A fresh perspective",
    "content": "Something worth sharing starts here.",
    "version": 1
  }
}

Open the same workspace in Postard to find the saved draft. Saving does not publish it. Avoid blindly retrying this POST after a connection failure: the request may already have succeeded, and app-session draft POSTs have no replay protection. For customer-key automation, use a UUID Idempotency-Key header as described in the authentication guide.

Next steps

Read the REST reference for input bounds and error codes, or use the MCP guide to connect a compatible AI client through OAuth.