API Endpoints

Coming Soon — API Access Not Yet Public

The Distill API is currently for internal use during early access and is not yet publicly available for third-party integrations. The endpoints documented here reflect the current internal implementation. Public API access with stable keys and versioning will be announced at a later date.

The Distill API lets you integrate newsletter processing and sending into your own workflows. All API requests are made over HTTPS to your app's base URL. The API follows REST conventions and returns JSON responses.

The Distill API is subject to change during early access. Endpoints and response formats may be updated without notice. Pin your integration to a specific behavior and test after updates.

Authentication

All API requests require a Bearer token obtained from Supabase authentication. To get a token:

Call the Supabase auth endpoint with your credentials to receive a session.
Extract the access_token from the session response.
Include it in the Authorization header of every API request.

# Example: get a token
curl -X POST https://your-project.supabase.co/auth/v1/token?grant_type=password \
  -H "apikey: YOUR_SUPABASE_ANON_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "yourpassword"}'

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 3600
}

Include the token in subsequent requests:

-H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Tokens expire after 1 hour by default. Refresh them using the Supabase auth refresh endpoint.

Endpoints

Process Link

Scrapes a URL using Firecrawl, generates an AI summary using Gemini, and adds the processed link to a newsletter issue.

POST /api/process-link

Request body:

{
  "url": "https://example.com/article",
  "issue_id": "b3c8e1a2-4f7d-4e9b-8f1c-2d3a5e6f7890"
}

Field	Type	Required	Description
`url`	string	Yes	The URL to scrape and summarize
`issue_id`	string (UUID)	Yes	The issue to add the processed link to

Example request:

curl -X POST https://app.distill.ink/api/process-link \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://techcrunch.com/2025/01/15/example-article",
    "issue_id": "b3c8e1a2-4f7d-4e9b-8f1c-2d3a5e6f7890"
  }'

Example response:

{
  "link": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "title": "Example Article Title",
    "url": "https://techcrunch.com/2025/01/15/example-article",
    "summary": "A brief AI-generated summary of the article content...",
    "category_id": null,
    "position": 3,
    "created_at": "2025-01-15T14:22:01Z"
  }
}

Processing is synchronous — the response is returned after scraping and summarization complete. For pages that load slowly, allow up to 30 seconds for a response.

Process Links (Bulk)

Processes multiple URLs in a single request. Each URL is scraped and summarized independently. Partial success is supported — if some URLs fail, the rest are still processed and returned.

POST /api/process-link-bulk

Request body:

{
  "urls": [
    "https://example.com/article-1",
    "https://example.com/article-2"
  ],
  "issue_id": "b3c8e1a2-4f7d-4e9b-8f1c-2d3a5e6f7890"
}

Field	Type	Required	Description
`urls`	string[]	Yes	Array of URLs to process (maximum 20 per request)
`issue_id`	string (UUID)	Yes	The issue to add all processed links to

Example request:

curl -X POST https://app.distill.ink/api/process-link-bulk \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": [
      "https://techcrunch.com/2025/01/15/article-one",
      "https://techcrunch.com/2025/01/15/article-two"
    ],
    "issue_id": "b3c8e1a2-4f7d-4e9b-8f1c-2d3a5e6f7890"
  }'

Example response:

{
  "links": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "title": "Article One Title",
      "url": "https://techcrunch.com/2025/01/15/article-one",
      "summary": "Summary of article one..."
    },
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f01234567891",
      "title": "Article Two Title",
      "url": "https://techcrunch.com/2025/01/15/article-two",
      "summary": "Summary of article two..."
    }
  ],
  "errors": []
}

If any URLs fail to process, they appear in the errors array with the URL and a reason. Successfully processed links appear in links regardless of any failures.

Parameter	Type	Required	Description
`workspace_id`	string (UUID)	Yes	The workspace to retrieve categories for

Field	Type	Required	Description
`issue_id`	string (UUID)	Yes	The issue to send
`list_id`	string (UUID)	Yes	The subscriber list to send to

Generate Preview

Renders the newsletter issue as HTML and returns the rendered preview. Use this to verify your content renders correctly before sending.

POST /api/generate-preview

Request body:

{
  "issue_id": "b3c8e1a2-4f7d-4e9b-8f1c-2d3a5e6f7890"
}

Example request:

curl -X POST https://app.distill.ink/api/generate-preview \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"issue_id": "b3c8e1a2-4f7d-4e9b-8f1c-2d3a5e6f7890"}'

Example response:

{
  "html": "<!DOCTYPE html><html><head>...</head><body>...</body></html>",
  "subject": "Your Weekly Digest — January 15, 2025"
}

The returned HTML includes all inline styles for email client compatibility.

Rate Limits

All API endpoints are rate-limited per authenticated user. Rate limits vary by plan tier — refer to your plan's limits at distill.ink/pricing. If you exceed the rate limit, the API returns 429 Too Many Requests with a Retry-After header indicating when you can retry.

Error Handling

All errors follow a consistent response format:

{
  "error": "A human-readable description of what went wrong."
}

Status Code	Meaning
`400`	Bad request — malformed JSON, missing required fields, or invalid field values
`401`	Unauthorized — missing or invalid Bearer token
`403`	Forbidden — authenticated but not authorized to access the requested resource
`409`	Conflict — resource state prevents the operation (e.g., issue already sent)
`429`	Too Many Requests — rate limit exceeded; check the `Retry-After` header
`500`	Internal Server Error — unexpected server-side error; contact support if persistent

For 500 errors that persist, contact support at support@distill.ink with the request ID from the response headers (if present).

Next steps

Coming Soon — API Access Not Yet Public

The Distill API is subject to change during early access. Endpoints and response formats may be updated without notice. Pin your integration to a specific behavior and test after updates.

Authentication

All API requests require a Bearer token obtained from Supabase authentication. To get a token:

Call the Supabase auth endpoint with your credentials to receive a session.
Extract the access_token from the session response.
Include it in the Authorization header of every API request.

# Example: get a token
curl -X POST https://your-project.supabase.co/auth/v1/token?grant_type=password \
  -H "apikey: YOUR_SUPABASE_ANON_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "yourpassword"}'

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 3600
}

Include the token in subsequent requests:

-H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Tokens expire after 1 hour by default. Refresh them using the Supabase auth refresh endpoint.

Endpoints

Process Link

Scrapes a URL using Firecrawl, generates an AI summary using Gemini, and adds the processed link to a newsletter issue.

POST /api/process-link

Request body:

{
  "url": "https://example.com/article",
  "issue_id": "b3c8e1a2-4f7d-4e9b-8f1c-2d3a5e6f7890"
}

Field	Type	Required	Description
`url`	string	Yes	The URL to scrape and summarize
`issue_id`	string (UUID)	Yes	The issue to add the processed link to

Example request:

curl -X POST https://app.distill.ink/api/process-link \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://techcrunch.com/2025/01/15/example-article",
    "issue_id": "b3c8e1a2-4f7d-4e9b-8f1c-2d3a5e6f7890"
  }'

Example response:

{
  "link": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "title": "Example Article Title",
    "url": "https://techcrunch.com/2025/01/15/example-article",
    "summary": "A brief AI-generated summary of the article content...",
    "category_id": null,
    "position": 3,
    "created_at": "2025-01-15T14:22:01Z"
  }
}

Processing is synchronous — the response is returned after scraping and summarization complete. For pages that load slowly, allow up to 30 seconds for a response.

Process Links (Bulk)

Processes multiple URLs in a single request. Each URL is scraped and summarized independently. Partial success is supported — if some URLs fail, the rest are still processed and returned.

POST /api/process-link-bulk

Request body:

{
  "urls": [
    "https://example.com/article-1",
    "https://example.com/article-2"
  ],
  "issue_id": "b3c8e1a2-4f7d-4e9b-8f1c-2d3a5e6f7890"
}

Field	Type	Required	Description
`urls`	string[]	Yes	Array of URLs to process (maximum 20 per request)
`issue_id`	string (UUID)	Yes	The issue to add all processed links to

Example request:

curl -X POST https://app.distill.ink/api/process-link-bulk \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": [
      "https://techcrunch.com/2025/01/15/article-one",
      "https://techcrunch.com/2025/01/15/article-two"
    ],
    "issue_id": "b3c8e1a2-4f7d-4e9b-8f1c-2d3a5e6f7890"
  }'

Example response:

{
  "links": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "title": "Article One Title",
      "url": "https://techcrunch.com/2025/01/15/article-one",
      "summary": "Summary of article one..."
    },
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f01234567891",
      "title": "Article Two Title",
      "url": "https://techcrunch.com/2025/01/15/article-two",
      "summary": "Summary of article two..."
    }
  ],
  "errors": []
}

If any URLs fail to process, they appear in the errors array with the URL and a reason. Successfully processed links appear in links regardless of any failures.

Parameter	Type	Required	Description
`workspace_id`	string (UUID)	Yes	The workspace to retrieve categories for

Field	Type	Required	Description
`issue_id`	string (UUID)	Yes	The issue to send
`list_id`	string (UUID)	Yes	The subscriber list to send to

Generate Preview

Renders the newsletter issue as HTML and returns the rendered preview. Use this to verify your content renders correctly before sending.

POST /api/generate-preview

Request body:

{
  "issue_id": "b3c8e1a2-4f7d-4e9b-8f1c-2d3a5e6f7890"
}

Example request:

curl -X POST https://app.distill.ink/api/generate-preview \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"issue_id": "b3c8e1a2-4f7d-4e9b-8f1c-2d3a5e6f7890"}'

Example response:

{
  "html": "<!DOCTYPE html><html><head>...</head><body>...</body></html>",
  "subject": "Your Weekly Digest — January 15, 2025"
}

The returned HTML includes all inline styles for email client compatibility.

Rate Limits

Error Handling

All errors follow a consistent response format:

{
  "error": "A human-readable description of what went wrong."
}

Status Code	Meaning
`400`	Bad request — malformed JSON, missing required fields, or invalid field values
`401`	Unauthorized — missing or invalid Bearer token
`403`	Forbidden — authenticated but not authorized to access the requested resource
`409`	Conflict — resource state prevents the operation (e.g., issue already sent)
`429`	Too Many Requests — rate limit exceeded; check the `Retry-After` header
`500`	Internal Server Error — unexpected server-side error; contact support if persistent

For 500 errors that persist, contact support at support@distill.ink with the request ID from the response headers (if present).

Authentication

Endpoints

Process Link

Process Links (Bulk)

Categories

Generate Preview

Rate Limits

Error Handling

Next steps

On this page

API Endpoints

Authentication

Endpoints

Process Link

Process Links (Bulk)

Categories

Generate Preview

Rate Limits

Error Handling

Next steps

On this page