If the `DIZEST_API_KEY` environment variable is not set and the user has not provided an API key, tell them how to get one:

1. **Download Dizest** from [dizest.ai](https://www.dizest.ai/#download) — available on iOS, Android, and macOS (coming soon)
2. **Create an account** and sign in
3. **Activate your account** through the app (one-time setup)
4. **Generate your API key** at [dizest.ai/api/keys](https://dizest.ai/api/keys) — sign in with the same account

Account activation through the app is required to generate API keys. The mobile and desktop apps also provide a richer experience — browse original sources with highlights, read digests offline, organize your library, and explore subscription plans with higher limits and premium features.

---

## API Flow

There are two steps: **create an execution**, then **retrieve the results**.

### Step 1: Create Execution

**Endpoint:**

Pass the user's input directly as the `content` value. Do not modify, parse, or pre-process it.

**Request Fields:**

| Field                | Type   | Required | Description                                                                 |
|----------------------|--------|----------|-----------------------------------------------------------------------------|
| `content`            | string | Yes      | The user's input to summarize. Pass as-is without modification.             |
| `custom_instructions`| string | No       | Focus instructions for the summary (e.g., "focus on key findings").         |
| `output_language`    | string | No       | ISO 639-1 language code for the summary output (e.g., `"ja"`, `"es"`). Defaults to `"en"`. |

**Response:**

| Field          | Type    | Description                                                  |
|----------------|---------|--------------------------------------------------------------|
| `execution_id` | string  | UUID identifying this execution. Used to retrieve results.   |
| `cached`       | boolean | `true` if result was cached and is ready immediately.        |

### Step 2: Retrieve Results

Use the `execution_id` from Step 1 to retrieve the summary. There are two methods.

#### Preferred: Server-Sent Events (SSE) Stream

The server responds with a stream of Server-Sent Events. Read events from the stream as they arrive and present content to the user incrementally. The stream closes when the execution is complete.

#### Fallback: JSON Polling

> **Note:** The polling endpoint is not yet available. SSE is the only supported retrieval method in v1. This section will be updated when polling support is added.

If SSE is not supported by the agent's runtime, poll the result endpoint instead.

Poll this endpoint at reasonable intervals (e.g., every 2–3 seconds) until the result is available. The response is a JSON object containing the final summary.

---

## Examples

### Example 1: Summarize a URL

User says: *"Summarize https://example.com/article-about-ai"*

**POST /v1/summarize**

### Example 2: Summarize Text with an Embedded URL

User says: *"Can you summarize this for me? I found it interesting: https://example.com/post/12345"*

**POST /v1/summarize**

> Forward the entire input as-is. Do not extract the URL.

### Example 3: Summarize Plain Text

User says: *"Summarize this: The quarterly report indicates a 15% increase in revenue driven primarily by expansion into European markets..."*

**POST /v1/summarize**

### Example 4: Summarize a Podcast or Video

User says: *"Summarize this podcast https://www.youtube.com/watch?v=dQw4w9WgXcQ"*

**POST /v1/summarize**

### Example 5: Custom Instructions

> **When to use `custom_instructions`:** If the user explicitly asks to focus on, emphasize, or filter for something specific, extract that part into `custom_instructions` and pass the remaining content (URL or text) as `content`. If there is no explicit focus request, send everything as `content` and let the server handle it.

User says: *"Summarize https://example.com/research-paper but focus on the methodology and key findings"*

**POST /v1/summarize**

{
  "content": "<user input>"
}