# Claude Code setup
Source: https://docs.parsagon.io/ai-tools/claude-code

Configure Claude Code for your documentation workflow

Set up Claude Code to help you write and maintain your Mintlify documentation.

## Prerequisites

* Active Claude subscription (Pro, Max, or API access)

## Setup

<Steps>
  <Step title="Install Claude Code">
    ```bash theme={null}
    npm install -g @anthropic-ai/claude-code
    ```
  </Step>

  <Step title="Install the Mintlify skill">
    In your docs directory, run:

    ```bash theme={null}
    npx skills add https://mintlify.com/docs
    ```

    This gives Claude Code Mintlify's component reference, writing standards,
    and workflow guidance.
  </Step>

  <Step title="Customize project instructions">
    Edit `AGENTS.md` in your project root to add project-specific terminology,
    style preferences, and content boundaries.
  </Step>

  <Step title="Start writing with Claude Code">
    ```bash theme={null}
    claude
    ```
  </Step>
</Steps>


# Coding agent skill
Source: https://docs.parsagon.io/ai-tools/coding-agent-skill

Add Parsagon API guidance to your coding agent

Add this skill to your coding agent so it can build against the Parsagon API with the correct authentication, endpoint choices, request schema, and test mode behavior.

## Where to install it

Create one of these folders in your codebase:

```text .agents path theme={null}
.agents/skills/parsagon-api/
```

```text Claude Code path theme={null}
.claude/skills/parsagon-api/
```

Then create a `SKILL.md` file inside that folder.

## Skill file

Copy this into `SKILL.md`:

````markdown SKILL.md theme={null}
---
name: parsagon-api
description: Use when building, debugging, or reviewing integrations with the Parsagon API.
---

# Parsagon API

Use this skill when code interacts with the Parsagon API.

## Product context

Parsagon provides programmatic access to a daily-updated dataset of legislation, regulations, government publications, and related monitoring data across 70+ countries.

The API base URL is:

```text
https://parsagon.io/api/events/v1/
```

## Authentication

Authenticate every request with an API key in the `Authorization` header.

```http
Authorization: Token <PARSAGON_API_KEY>
```

Never hardcode API keys. Read keys from environment variables, secret stores, or the host application's existing configuration system.

## Endpoint selection

Use **Quick Search** (`POST /quick-search/`) for one-off searches that need immediate results. The maximum search window is 72 hours.

Quick Search returns results directly in the response. It still creates a Search object and counts toward quota.

Use **Advanced Search** (`POST /search/`) when the integration needs a persistent Search object, asynchronous processing, a search window up to 90 days, or an AI-generated report.

Use **Retrieve Advanced Search** (`GET /search/{search_id}/`) to poll for Advanced Search results.

Use **List Searches** (`GET /search/`) to retrieve searches associated with the account.

Use **Get Category Sources v2** (`GET https://parsagon.io/api/events/v2/categories/{category_id}/sources/`) when the integration needs raw source material for a category without AI filtering or summarization.

Use **Create Report** (`POST /reports/`) when the integration needs to generate a standalone AI report from a topic, structure, audience, and target length. Use **Retrieve Report** (`GET /reports/{report_id}/`) to poll until `result` or `error` is non-null.

Use **Get Category Sources v2** to retrieve a comprehensive list of sources for a category. Results are cursor-paginated and reverse chronological, newest first. The response includes `next`, `previous`, and `results`; it does not include `count`. Results cover up to the last 90 days, but some categories may have less than 90 days available. Use `limit` to request up to `1000` sources per page, and follow the opaque `cursor` token from `next` or `previous` URLs to paginate.

The legacy v1 category sources endpoint (`GET /categories/{category_id}/sources/` under the v1 base URL) uses limit/offset pagination and includes `count`. Prefer v2 for new integrations, especially for large categories.

Use **Quick Search** or **Advanced Search** when the integration needs to filter sources, such as filtering news articles to only return articles that announce new laws or regulations.

Do not use Quick Search or Advanced Search when the integration needs unfiltered results. If the integration needs all results, especially in chronological order, use Get Category Sources instead. Quick Search and Advanced Search are built for filtering and cannot reliably return every source in chronological order.

Use **Advanced Search** when the integration needs to extract structured data from each source. For example, use the edit prompt to ask Parsagon to return JSON with specific fields about source contents.

If the integration needs all results and then needs to edit or transform them, retrieve all data with Get Category Sources and transform the data in the host application. If the transformation would be very hard to implement locally, tell the user to reach out to Parsagon to discuss a custom transformation through a custom category.

## Shared request schema

Quick Search and Advanced Search use the same core request body:

```json
{
  "categories": [1],
  "context": "User is a Government Relations Manager for an aerospace company in the UK.",
  "filter_prompt": "Government funding and subsidies for aerospace R&D innovation\nWorkforce development and skills programs for aerospace manufacturing, engineering, and skilled labour",
  "date_range": {
    "duration_seconds": 259200
  }
}
```

Use `categories` for category IDs.

Parsagon does not keep a comprehensive public list of category IDs. Each user gets category IDs specific to their needs, and some categories may be custom-made for that user. If the category's contents are not clear, ask the user what kind of data lives in each category, such as legislation, regulations, news, general policy developments, or all of the above. Use that context to choose the right API call.

Use `context` to tailor results to the customer, organization, or workflow. Keep it under 1000 characters.

Use `filter_prompt` to describe what to search for. Prefer one policy topic per line. Keep it under 5000 characters.

Use `edit_prompt` with Advanced Search when the integration needs `edited_results`. Keep it under 5000 characters. Omit `edit_prompt` if the integration only needs raw `search_results`.

Use `labels` to attach string key-value metadata to a Quick Search or Advanced Search for record keeping, such as project, team, customer, or workflow IDs.

Use `date_range.duration_seconds` for relative searches, or use `date_range.start_date` and `date_range.end_date` for fixed UTC ISO 8601 ranges.

## Date range limits

Quick Search supports a maximum window of 72 hours, so `duration_seconds` must be at most `259200`.

Advanced Search supports a maximum window of 90 days, so `duration_seconds` must be at most `7776000`.

The earliest supported `start_date` is 90 days before the request time.

## Test mode

Use `is_test: true` to validate request handling without running a source search or report generation task.

Required fields are still validated in test mode. For Search endpoints, this includes `categories`, `filter_prompt`, and `date_range`. For Create Report, this includes `topic`, `structure`, `audience`, and `length`.

Quick Search returns example search results immediately in test mode.

Advanced Search creates a dummy Search object in test mode. Retrieve it with Get Search to inspect the dummy results.

Use `test_data.search_results` when tests need deterministic sample results.

Use `test_data.edited_results` to test downstream handling of custom Advanced Search `edited_results`. This value is stored exactly as provided. The API does not run `edit_prompt` in test mode.

Use `test_data.result` to test downstream handling of custom Create Report output. This value is stored exactly as provided.

```json
{
  "categories": [1],
  "context": "User is testing an API integration.",
  "filter_prompt": "Example policy updates",
  "date_range": {
    "duration_seconds": 86400
  },
  "is_test": true,
  "test_data": {
    "search_results": [
      {
        "url": "https://example.com/policy-update",
        "title": "Example policy update",
        "summary": "Example summary returned in test mode.",
        "date": "2026-02-03",
        "type": "ARTICLE"
      }
    ]
  }
}
```

```json
{
  "topic": "Example policy report",
  "structure": "Executive summary and key developments",
  "audience": "Policy team",
  "length": "SHORT_MEMO",
  "is_test": true,
  "test_data": {
    "result": {
      "text": "# Example report\n\nExample report content returned in test mode.",
      "html": "<h1>Example report</h1><p>Example report content returned in test mode.</p>",
      "type": "html"
    }
  }
}
```

## Implementation guidance

Prefer typed request and response models when the host project uses a typed language.

Validate date windows before sending requests so users get local errors for unsupported ranges.

Use request timeouts of at least 60 seconds.

Use retries for API requests, especially for transient network errors and 5xx responses.

Set `Content-Type: application/json` for requests with JSON bodies.

Handle asynchronous Advanced Search flows by polling `GET /search/{search_id}/` until `search_results`, `edited_results`, or `error` is non-null.

Handle asynchronous Report flows by polling `GET /reports/{report_id}/` until `result` or `error` is non-null.

Advanced Searches typically complete within 1-5 minutes. Poll approximately once every 15 seconds.

Write integration tests with `is_test: true` when possible.

Surface Parsagon API errors with enough context to debug the request, but do not log API keys.

## Search results

Search result objects may include these fields:

- `url`: URL of the source document.
- `title`: Title of the document.
- `date`: Date when Parsagon collected the document. This may differ slightly from the original publication date.
- `text`: Full text or main body of the document.
- `summary`: AI-generated 1-2 sentence summary of the document.
- `type`: Document type. Usually `"ARTICLE"` for press releases, announcements, generic articles, and similar content, or `"LAW"` for bills and legislation.
- `extra_data`: Additional metadata. Fields are not guaranteed and depend on the jurisdiction and source type. For legislation data, `extra_data` often but not always includes `bill`, `status`, `last_action`, and `last_action_date`; `bill` is the bill ID. For regulations, `extra_data` often but not always includes `agency_name`, `document_type`, `comment_deadline`, and `effective_date`.
- `search_topics`: Zero-based indexes of `filter_prompt` lines relevant to the result.
- `jurisdictions`: Jurisdictions that apply to the result.

## Coverage assessment

When assessing whether jurisdictions are included in Parsagon data, account for different publication patterns across jurisdictions.

Some governments and legislatures may be in recess for months and may not publish legislation or regulations during that time.

Some jurisdictions naturally publish thousands of items per month, while others may only publish a handful of items for a given category.

Do not treat low volume in a short date range as proof that a jurisdiction is missing from coverage.

## Documentation

Use the Parsagon API docs for endpoint-specific details:

```text
https://docs.parsagon.io/api-reference/introduction
```
````

## Suggested project instruction

Add this note to your agent's project instructions so it loads the skill when needed:

```markdown theme={null}
When building, debugging, or reviewing code that calls the Parsagon API, use the `parsagon-api` skill.
```


# Cursor setup
Source: https://docs.parsagon.io/ai-tools/cursor

Configure Cursor for your documentation workflow

Set up Cursor to help you write and maintain your Mintlify documentation.

## Prerequisites

* Cursor editor installed

## Setup

<Steps>
  <Step title="Open your docs directory in Cursor">
    Open the root of your documentation repository where `docs.json` is located.
  </Step>

  <Step title="Install the Mintlify skill">
    In the integrated terminal, run:

    ```bash theme={null}
    npx skills add https://mintlify.com/docs
    ```

    This gives Cursor Mintlify's component reference, writing standards,
    and workflow guidance.
  </Step>

  <Step title="Customize project instructions">
    Edit `AGENTS.md` in your project root to add project-specific terminology,
    style preferences, and content boundaries.
  </Step>

  <Step title="Start writing with Cursor">
    Open a file and use Cursor's AI features to draft and edit documentation.
  </Step>
</Steps>


# Windsurf setup
Source: https://docs.parsagon.io/ai-tools/windsurf

Configure Windsurf for your documentation workflow

Set up Windsurf's Cascade AI assistant to help you write and maintain your Mintlify documentation.

## Prerequisites

* Windsurf editor installed

## Setup

<Steps>
  <Step title="Open your docs directory in Windsurf">
    Open the root of your documentation repository where `docs.json` is located.
  </Step>

  <Step title="Install the Mintlify skill">
    In the integrated terminal, run:

    ```bash theme={null}
    npx skills add https://mintlify.com/docs
    ```

    This gives Windsurf Mintlify's component reference, writing standards,
    and workflow guidance.
  </Step>

  <Step title="Customize project instructions">
    Edit `AGENTS.md` in your project root to add project-specific terminology,
    style preferences, and content boundaries.
  </Step>

  <Step title="Start writing with Cascade">
    Open a file and use Cascade to draft and edit documentation.
  </Step>
</Steps>


# Create advanced search
Source: https://docs.parsagon.io/api-reference/endpoint/advanced-search

POST https://parsagon.io/api/events/v1/search/
Create a persistent Search object processed asynchronously, with results and an AI-generated report available via polling.

The Advanced Search endpoint creates a persistent Search object. The server processes the search asynchronously. Use the returned `id` to poll for completion.

Unlike Quick Search, Advanced Search supports date ranges up to 90 days and produces an AI-generated report alongside raw results.

## Request body

<ParamField type="array">
  Array of category IDs to include in the search results.
</ParamField>

<ParamField type="string">
  Additional context for the AI to tailor the search and reporting (for example, your organization or focus area). Maximum 1000 characters.
</ParamField>

<ParamField type="string">
  A list of policy topics to search for, one per line. Longer, descriptive phrases work best. Maximum 5000 characters.
</ParamField>

<ParamField type="string">
  Optional instructions for formatting or transforming the search results into `edited_results`. Omit this field if you only need raw `search_results`. Maximum 5000 characters.
</ParamField>

<ParamField type="object">
  A dictionary of string key-value pairs for your own record keeping. Use this to attach metadata to the search, such as the project or team it belongs to (for example, `{"project": "tax-reform", "team": "policy"}`).
</ParamField>

<ParamField type="boolean">
  Set to `true` to validate the request and create a Search with example data without running a source search. Required fields such as `categories`, `filter_prompt`, and `date_range` are still validated normally.
</ParamField>

<ParamField type="object">
  Custom dummy data to store when `is_test` is `true`. Use this to test downstream handling of `search_results` or custom `edited_results` formats.

  <Expandable title="Test data fields">
    <ParamField type="array">
      Array of search result objects to store instead of Parsagon's built-in example results.
    </ParamField>

    <ParamField type="any">
      Custom edited output to store as `edited_results`. This value is not generated from `edit_prompt`; it is stored exactly as provided.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object">
  Time period to search within. May cover up to **90 days** — use either `start_date`/`end_date` or `duration_seconds` ≤ 7776000.

  <Expandable title="Fixed range">
    <ParamField type="string">
      ISO 8601 datetime (UTC). The earliest supported value is 90 days before the time of the request.
    </ParamField>

    <ParamField type="string">
      ISO 8601 datetime (UTC).
    </ParamField>
  </Expandable>

  <Expandable title="Relative duration">
    <ParamField type="number">
      Positive number of seconds before "now" to search within (maximum 7776000).
    </ParamField>
  </Expandable>
</ParamField>

## Response

On success, returns the created Search object. The create response does not include `search_results` or `edited_results`. Use the returned `id` to [retrieve the Search](/api-reference/endpoint/get-search) and read results.

<ResponseField name="id" type="number | string">
  Unique identifier for the Search. Use this to [retrieve results](/api-reference/endpoint/get-search).
</ResponseField>

<ResponseField name="categories" type="array">
  Array of category IDs used in the search.
</ResponseField>

<ResponseField name="context" type="string">
  Context provided in the request.
</ResponseField>

<ResponseField name="filter_prompt" type="string">
  Filter prompt provided in the request.
</ResponseField>

<ResponseField name="edit_prompt" type="string">
  Edit prompt provided in the request.
</ResponseField>

<ResponseField name="labels" type="object">
  Labels provided in the request.
</ResponseField>

<ResponseField name="is_test" type="boolean">
  Whether the Search was created in test mode.
</ResponseField>

<ResponseField name="date_range" type="object">
  The date range used, containing either `start_date` and `end_date`, or `duration_seconds`.
</ResponseField>

<ResponseField name="created_at" type="string">
  Timestamp when the Search was created (ISO 8601, UTC).
</ResponseField>

<ResponseField name="n_potential" type="number">
  Estimated number of candidate results to process.
</ResponseField>

<ResponseField name="n_processed" type="number">
  Number of candidate results processed so far.
</ResponseField>

<ResponseField name="returned_up_to_idx" type="number">
  Internal pagination position for additional result pages.
</ResponseField>

<ResponseField name="uuid" type="string">
  Public UUID for the Search.
</ResponseField>

<ResponseField name="error" type="string | null">
  Error message if an error occurred; otherwise `null`.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://parsagon.io/api/events/v1/search/" \
    -H "Authorization: Token YOUR_API_KEY_HERE" \
    -H "Content-Type: application/json" \
    -d '{
      "categories": [74],
      "context": "User needs to keep track of financial services regulations in the UK",
      "filter_prompt": "Policies related to financial market stability and supervision of financial institutions\nConsumer protection regulations related to financial products and services",
      "date_range": {
        "start_date": "2026-01-30T00:00",
        "end_date": "2026-02-01T00:00"
      }
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json Example response theme={null}
  {
    "id": 12345,
    "categories": [74],
    "context": "User needs to keep track of financial services regulations in the UK",
    "filter_prompt": "Policies related to financial market stability and supervision of financial institutions\nConsumer protection regulations related to financial products and services",
    "edit_prompt": "",
    "created_at": "2026-02-01T12:00:00Z",
    "language": "en-us",
    "custom_summarize": false,
    "n_potential": 0,
    "n_processed": 0,
    "error": null,
    "date_range": {
      "start_date": "2026-01-30T00:00:00+00:00",
      "end_date": "2026-02-01T00:00:00+00:00"
    },
    "returned_up_to_idx": 0,
    "uuid": "90df802d-c875-4dd7-830a-99242cfd74e0",
    "labels": {},
    "is_test": false
  }
  ```
</ResponseExample>

## Test mode

Use `is_test: true` to test your integration without running a source search. The endpoint still validates the request body the same way it does for a normal Advanced Search request.

In test mode, `POST /search/` returns a dummy Search object with an `id`. Retrieve that Search with [Get Search](/api-reference/endpoint/get-search) to read the dummy `search_results` and `edited_results`. The API does not run `edit_prompt` in test mode. If you include `test_data.edited_results`, that value is stored exactly as provided.

```json Example test request body theme={null}
{
  "categories": [74],
  "context": "User needs to keep track of financial services regulations in the UK",
  "filter_prompt": "Policies related to financial market stability and supervision of financial institutions",
  "edit_prompt": "Return a JSON report grouped by regulator",
  "date_range": {
    "duration_seconds": 604800
  },
  "is_test": true,
  "test_data": {
    "search_results": [
      {
        "url": "https://example.com/regulatory-update",
        "title": "Example regulatory update",
        "text": "Example source text for testing.",
        "summary": "Example summary returned in test mode.",
        "date": "2026-02-03",
        "type": "ARTICLE",
        "extra_data": {},
        "search_topics": [0],
        "jurisdictions": ["UK"]
      }
    ],
    "edited_results": {
      "report_title": "Example financial services report",
      "items": [
        {
          "regulator": "Example regulator",
          "summary": "Example custom report item."
        }
      ]
    }
  }
}
```

The create response contains the dummy Search object's `id`. Use that `id` to retrieve the stored dummy data:

```bash Retrieve test Search theme={null}
curl -X GET "https://parsagon.io/api/events/v1/search/12345/" \
  -H "Authorization: Token YOUR_API_KEY_HERE"
```

```json Example test retrieval response theme={null}
{
  "id": 12345,
  "categories": [74],
  "context": "User needs to keep track of financial services regulations in the UK",
  "filter_prompt": "Policies related to financial market stability and supervision of financial institutions",
  "edit_prompt": "Return a JSON report grouped by regulator",
  "is_test": true,
  "search_results": [
    {
      "url": "https://example.com/regulatory-update",
      "title": "Example regulatory update",
      "text": "Example source text for testing.",
      "summary": "Example summary returned in test mode.",
      "date": "2026-02-03",
      "type": "ARTICLE",
      "extra_data": {},
      "search_topics": [0],
      "jurisdictions": ["UK"]
    }
  ],
  "edited_results": {
    "report_title": "Example financial services report",
    "items": [
      {
        "regulator": "Example regulator",
        "summary": "Example custom report item."
      }
    ]
  },
  "error": null
}
```


# Get category sources
Source: https://docs.parsagon.io/api-reference/endpoint/category-sources

GET https://parsagon.io/api/events/v1/categories/{category_id}/sources/
Retrieve all sources collected for a given data category in chronological order, up to 90 days back.

Returns a chronological list of all sources collected for the specified category. Results cover up to the last 90 days (some categories may have less than 90 days available).

## Path parameters

<ParamField type="number">
  The ID of the data category to retrieve sources for.
</ParamField>

## Response

<ResponseField name="count" type="number">
  Total number of sources available for the category.
</ResponseField>

<ResponseField name="next" type="string | null">
  URL for the next page of results, or `null` if this is the last page.
</ResponseField>

<ResponseField name="previous" type="string | null">
  URL for the previous page of results, or `null` if this is the first page.
</ResponseField>

<ResponseField name="results" type="array">
  Array of source objects in chronological order (oldest first). Each object has the same fields as a [Quick Search](/api-reference/endpoint/quick-search) result.
</ResponseField>

<ResponseExample>
  ```json Example response theme={null}
  {
    "count": 34909,
    "next": "http://parsagon.io/api/events/v1/categories/1377/sources/?limit=10&offset=10",
    "previous": null,
    "results": [
      {
        "url": "https://www.nps.gov/cure/learn/news/curecanti-national-recreation-area-seeks-input-on-upgrades-to-water-and-wastewater-systems.htm",
        "title": "Curecanti National Recreation Area Seeks Input on Upgrades to Water and Wastewater Systems",
        "text": "Gunnison, Colo. – The National Park Service seeks public input on a proposed project to replace the water and wastewater systems within Curecanti National Recreation Area.\n\nThe proposed project will focus on...",
        "summary": "The National Park Service is requesting public feedback on plans to upgrade the aging water and wastewater infrastructure at Curecanti National Recreation Area's Elk Creek and Lake Fork Marinas and Campgrounds to improve efficiency and resilience.",
        "date": "2026-03-03",
        "type": "ARTICLE",
        "extra_data": {},
        "jurisdictions": ["US Colorado"]
      },
      ...
    ]
  }
  ```
</ResponseExample>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://parsagon.io/api/events/v1/categories/1/sources/" \
    -H "Authorization: Token YOUR_API_KEY_HERE"
  ```
</RequestExample>


# Get category sources v2
Source: https://docs.parsagon.io/api-reference/endpoint/category-sources-v2

GET https://parsagon.io/api/events/v2/categories/{category_id}/sources/
Retrieve sources collected for a given data category using cursor pagination, up to 90 days back.

Returns a reverse chronological list of sources collected for the specified category. Results cover up to the last 90 days (some categories may have less than 90 days available).

This endpoint uses cursor pagination for faster responses on large categories. The v1 endpoint remains available at `/api/events/v1/categories/{category_id}/sources/` and uses limit/offset pagination with a `count` field.

## Path parameters

<ParamField type="number">
  The ID of the data category to retrieve sources for.
</ParamField>

## Query parameters

<ParamField type="number">
  The maximum number of sources to return. Defaults to `100`; maximum `1000`.
</ParamField>

<ParamField type="string">
  Cursor token from the previous response's `next` or `previous` URL.
</ParamField>

## Response

<ResponseField name="next" type="string | null">
  URL for the next page of results, or `null` if this is the last page.
</ResponseField>

<ResponseField name="previous" type="string | null">
  URL for the previous page of results, or `null` if this is the first page.
</ResponseField>

<ResponseField name="results" type="array">
  Array of source objects in reverse chronological order (newest first). Each object has the same fields as a [Quick Search](/api-reference/endpoint/quick-search) result.
</ResponseField>

<ResponseExample>
  ```json Example response theme={null}
  {
    "next": "https://parsagon.io/api/events/v2/categories/1377/sources/?cursor=cD0yMDI2LTAzLTAzKzEyJTNBMDAlM0EwMCUyQjAwJTNBMDA%3D&limit=100",
    "previous": null,
    "results": [
      {
        "url": "https://www.nps.gov/cure/learn/news/curecanti-national-recreation-area-seeks-input-on-upgrades-to-water-and-wastewater-systems.htm",
        "title": "Curecanti National Recreation Area Seeks Input on Upgrades to Water and Wastewater Systems",
        "text": "Gunnison, Colo. – The National Park Service seeks public input on a proposed project to replace the water and wastewater systems within Curecanti National Recreation Area.\n\nThe proposed project will focus on...",
        "summary": "The National Park Service is requesting public feedback on plans to upgrade the aging water and wastewater infrastructure at Curecanti National Recreation Area's Elk Creek and Lake Fork Marinas and Campgrounds to improve efficiency and resilience.",
        "date": "2026-03-03",
        "type": "ARTICLE",
        "extra_data": {},
        "jurisdictions": ["US Colorado"]
      }
    ]
  }
  ```
</ResponseExample>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://parsagon.io/api/events/v2/categories/1/sources/?limit=100" \
    -H "Authorization: Token YOUR_API_KEY_HERE"
  ```
</RequestExample>


# Create report
Source: https://docs.parsagon.io/api-reference/endpoint/create-report

POST https://parsagon.io/api/events/v1/reports/
Create a persistent Report object processed asynchronously, with generated report content available via polling.

The Create Report endpoint creates a persistent Report object. The server processes the report asynchronously. Use the returned `id` to poll for completion.

## Request body

<ParamField type="string">
  Topic for the report. Maximum 1000 characters.
</ParamField>

<ParamField type="string">
  Instructions for the report structure. Maximum 5000 characters.
</ParamField>

<ParamField type="string">
  Intended audience for the report. Maximum 1000 characters.
</ParamField>

<ParamField type="string">
  Approximate report length. Must be one of `SHORT_MEMO`, `EXEC_MEMO`, `MID_REPORT`, or `LONG_REPORT`.
</ParamField>

<ParamField type="boolean">
  Set to `true` to validate the request and create a Report with example data without running report generation. Required fields such as `topic`, `structure`, `audience`, and `length` are still validated normally.
</ParamField>

<ParamField type="object">
  Custom dummy data to store when `is_test` is `true`. Use this to test downstream handling of report results.

  <Expandable title="Test data fields">
    <ParamField type="object">
      Custom report result to store instead of Parsagon's built-in example result. This value is stored exactly as provided.
    </ParamField>
  </Expandable>
</ParamField>

## Response

On success, returns the created Report object. For normal requests, `result` is `null` until processing completes. Use the returned `id` to [retrieve the Report](/api-reference/endpoint/get-report).

<ResponseField name="id" type="number | string">
  Unique identifier for the Report. Use this to retrieve results.
</ResponseField>

<ResponseField name="type" type="string">
  Report type. For this endpoint, the value is `BRIEF`.
</ResponseField>

<ResponseField name="fields" type="object">
  Stored request fields, including `topic`, `structure`, `audience`, and numeric target `length`.
</ResponseField>

<ResponseField name="created_at" type="string">
  Timestamp when the Report was created (ISO 8601, UTC).
</ResponseField>

<ResponseField name="finished_at" type="string | null">
  Timestamp when report generation finished, or `null` while processing.
</ResponseField>

<ResponseField name="result" type="object | null">
  Generated report content when processing is complete, or dummy report content in test mode.
</ResponseField>

<ResponseField name="progress" type="number">
  Processing progress from `0` to `100`.
</ResponseField>

<ResponseField name="error" type="string | null">
  Error message if report generation failed; otherwise `null`.
</ResponseField>

<ResponseField name="uuid" type="string">
  Public UUID for the Report.
</ResponseField>

<ResponseField name="is_test" type="boolean">
  Whether the Report was created in test mode.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://parsagon.io/api/events/v1/reports/" \
    -H "Authorization: Token YOUR_API_KEY_HERE" \
    -H "Content-Type: application/json" \
    -d '{
      "topic": "Financial services regulatory developments in the UK",
      "structure": "Executive summary, key developments, and implications",
      "audience": "Government relations team",
      "length": "SHORT_MEMO"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json Example response theme={null}
  {
    "id": 12345,
    "type": "BRIEF",
    "fields": {
      "topic": "Financial services regulatory developments in the UK",
      "structure": "Executive summary, key developments, and implications",
      "audience": "Government relations team",
      "length": 500
    },
    "created_at": "2026-02-01T12:00:00Z",
    "finished_at": null,
    "result": null,
    "progress": 0,
    "error": null,
    "uuid": "90df802d-c875-4dd7-830a-99242cfd74e0",
    "is_test": false
  }
  ```
</ResponseExample>

## Test mode

Use `is_test: true` to test your integration without running report generation. The endpoint still validates the request body the same way it does for a normal Create Report request.

In test mode, `POST /reports/` returns a dummy Report object with `result`, `progress: 100`, and `finished_at` populated. If you include `test_data.result`, that value is stored exactly as provided.

```json Example test request body theme={null}
{
  "topic": "Financial services regulatory developments in the UK",
  "structure": "Executive summary, key developments, and implications",
  "audience": "Government relations team",
  "length": "SHORT_MEMO",
  "is_test": true,
  "test_data": {
    "result": {
      "text": "# Example report\n\nExample report content returned in test mode.",
      "html": "<h1>Example report</h1><p>Example report content returned in test mode.</p>",
      "type": "html"
    }
  }
}
```

```json Example test response theme={null}
{
  "id": 12345,
  "type": "BRIEF",
  "fields": {
    "topic": "Financial services regulatory developments in the UK",
    "structure": "Executive summary, key developments, and implications",
    "audience": "Government relations team",
    "length": 500
  },
  "created_at": "2026-02-01T12:00:00Z",
  "finished_at": "2026-02-01T12:00:00Z",
  "result": {
    "text": "# Example report\n\nExample report content returned in test mode.",
    "html": "<h1>Example report</h1><p>Example report content returned in test mode.</p>",
    "type": "html"
  },
  "progress": 100,
  "error": null,
  "uuid": "90df802d-c875-4dd7-830a-99242cfd74e0",
  "is_test": true
}
```


# Retrieve report
Source: https://docs.parsagon.io/api-reference/endpoint/get-report

GET https://parsagon.io/api/events/v1/reports/{report_id}/
Retrieve the current state of a previously created Report, including generated report content when available.

Retrieve the current state of a previously created Report. Poll this endpoint after creating a report to check whether processing is complete.

<Info>
  Reports are processed asynchronously. Poll until `result` or `error` is non-null.
</Info>

## Path parameters

<ParamField type="string">
  The `id` returned when the Report was created.
</ParamField>

## Response

Returns a JSON object representing the Report, including metadata and generated content when available.

<Info>
  For Reports created with `is_test: true`, this endpoint returns the dummy `result` stored at creation time.
</Info>

<ResponseField name="id" type="number | string">
  Unique identifier for the Report.
</ResponseField>

<ResponseField name="type" type="string">
  Report type.
</ResponseField>

<ResponseField name="fields" type="object">
  Stored request fields.
</ResponseField>

<ResponseField name="created_at" type="string">
  Timestamp when the Report was created (ISO 8601, UTC).
</ResponseField>

<ResponseField name="finished_at" type="string | null">
  Timestamp when report generation finished, or `null` while processing.
</ResponseField>

<ResponseField name="result" type="object | null">
  Generated report content when processing is complete, `null` otherwise. For test reports, this is the built-in example result or the value provided in `test_data.result`.
</ResponseField>

<ResponseField name="progress" type="number">
  Processing progress from `0` to `100`.
</ResponseField>

<ResponseField name="error" type="string | null">
  Error message if report generation failed; otherwise `null`.
</ResponseField>

<ResponseField name="uuid" type="string">
  Public UUID for the Report.
</ResponseField>

<ResponseField name="is_test" type="boolean">
  Whether the Report was created in test mode.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://parsagon.io/api/events/v1/reports/12345/" \
    -H "Authorization: Token YOUR_API_KEY_HERE"
  ```
</RequestExample>


# Retrieve advanced search
Source: https://docs.parsagon.io/api-reference/endpoint/get-search

GET https://parsagon.io/api/events/v1/search/{search_id}/
Retrieve the current state of a previously created Advanced Search, including raw results and the AI-generated report.

Retrieve the current state of a previously created Advanced Search. Poll this endpoint after creating a search to check whether processing is complete.

<Info>
  Searches typically complete within **1–5 minutes**. Poll approximately **once every 15 seconds** until `search_results`, `edited_results`, and/or `error` are non-null.
</Info>

## Path parameters

<ParamField type="string">
  The `id` returned when the Search was created.
</ParamField>

## Response

Returns a JSON object representing the Search, including metadata, raw `search_results`, and `edited_results` when available.

<Info>
  For Advanced Search requests created with `is_test: true`, this endpoint returns the dummy `search_results` and `edited_results` stored at creation time.
</Info>

<ResponseField name="id" type="number | string">
  Unique identifier for the Search.
</ResponseField>

<ResponseField name="categories" type="array">
  Array of category IDs used in the search.
</ResponseField>

<ResponseField name="context" type="string">
  Context provided in the request.
</ResponseField>

<ResponseField name="filter_prompt" type="string">
  Filter prompt provided in the request.
</ResponseField>

<ResponseField name="edit_prompt" type="string">
  Edit prompt provided in the request.
</ResponseField>

<ResponseField name="labels" type="object">
  Labels provided in the request.
</ResponseField>

<ResponseField name="is_test" type="boolean">
  Whether the Search was created in test mode.
</ResponseField>

<ResponseField name="date_range" type="object">
  The date range used, containing either `start_date` and `end_date`, or `duration_seconds`.
</ResponseField>

<ResponseField name="created_at" type="string">
  Timestamp when the Search was created (ISO 8601, UTC).
</ResponseField>

<ResponseField name="search_results" type="array | null">
  Raw search results when processing is complete, `null` otherwise. Each item has the same fields as [Quick Search](/api-reference/endpoint/quick-search) results.
</ResponseField>

<ResponseField name="edited_results" type="any | null">
  AI-generated report when processing is complete, `null` otherwise. For test searches, this is the value provided in `test_data.edited_results`, if any.
</ResponseField>

<ResponseField name="error" type="string | null">
  Error message if the search failed; otherwise `null`.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://parsagon.io/api/events/v1/search/12345/" \
    -H "Authorization: Token YOUR_API_KEY_HERE"
  ```
</RequestExample>


# Get transcript
Source: https://docs.parsagon.io/api-reference/endpoint/get-transcript

GET https://parsagon.io/api/transcripts/v1/{id}
Retrieve detailed data for a single transcript, including full text and segment-level speaker and timing information.

Transcript text is typically available starting shortly after a hearing or debate begins, but lags the livestream by approximately 30 minutes or more. Speaker identities are not added to the data until after the hearing or debate is completed.

## Path parameters

<ParamField type="string">
  Unique identifier of the transcript.
</ParamField>

## Response

<ResponseField name="id" type="string">
  Unique identifier for the transcript.
</ResponseField>

<ResponseField name="title" type="string">
  Title of the transcript.
</ResponseField>

<ResponseField name="url" type="string">
  URL of the original audio or video source.
</ResponseField>

<ResponseField name="scheduled_time" type="string">
  Scheduled time of the event in ISO 8601 format.
</ResponseField>

<ResponseField name="text" type="string">
  Full transcript text.
</ResponseField>

<ResponseField name="transcript_status" type="string">
  Current status of the transcript.
</ResponseField>

<ResponseField name="extra_data" type="object">
  Additional transcript data, including segment-level details.

  <Expandable title="extra_data fields">
    <ResponseField name="segments" type="array">
      List of transcript segments with speaker and timing information.

      <Expandable title="Segment fields">
        <ResponseField name="start" type="number">
          Start time of the segment in seconds.
        </ResponseField>

        <ResponseField name="end" type="number">
          End time of the segment in seconds.
        </ResponseField>

        <ResponseField name="text" type="string">
          Transcribed text for this segment.
        </ResponseField>

        <ResponseField name="speaker" type="string">
          Speaker identifier for this segment.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://parsagon.io/api/transcripts/v1/abc123" \
    -H "Authorization: Token YOUR_API_KEY_HERE"
  ```
</RequestExample>

<ResponseExample>
  ```json Example response theme={null}
  {
    "id": 5103754,
    "title": "Committee on the Internal Market and Consumer Protection Ordinary meeting",
    "url": "https://multimedia.europarl.europa.eu/en/webstreaming/committee-on-internal-market-and-consumer-protection-ordinary-meeting_20260507-0900-COMMITTEE-IMCO",
    "scheduled_time": "2026-05-07T07:00:00Z",
    "text": "Anna Cavazzini:\r\n Good morning, dear colleagues. I suggest we start our IMCO session. Before I welcome our Commissioner for Consumer Protection...",
    "extra_data": {
      "segments": [
        {
          "text": " Good morning, dear colleagues. I suggest we start our IMCO session. Before I welcome our Commissioner for Consumer Protection...",
          "start": 2.545,
          "end": 149.511,
          "speaker": "Anna Cavazzini"
        },
        ...
      ]
    },
    "transcript_status": "FINISHED"
  }
  ```
</ResponseExample>


# Get jurisdiction usage
Source: https://docs.parsagon.io/api-reference/endpoint/jurisdiction-usage

GET https://parsagon.io/api/usage/v1/jurisdictions/
Retrieve report and source search usage grouped by jurisdiction.

Returns your report and source search usage grouped by jurisdiction. Usage only includes jurisdictions available to your account.

Each report counts once for every jurisdiction attached to it. Each source search counts once for every jurisdiction represented by its selected categories. Test reports and test source searches are excluded.

<Info>
  Without a custom date range, the endpoint returns usage for the current calendar month in UTC.
</Info>

## Query parameters

<ParamField type="string">
  Start of the usage period as an ISO 8601 timestamp. This value is inclusive and must be provided with `end`.
</ParamField>

<ParamField type="string">
  End of the usage period as an ISO 8601 timestamp. This value is exclusive and must be provided with `start`.
</ParamField>

Custom usage periods cannot exceed 366 days. If you provide only `start` or `end`, or request a longer period, the endpoint returns `400 Bad Request`.

## Response

<ResponseField name="user_id" type="integer">
  ID of the user whose usage is represented.
</ResponseField>

<ResponseField name="start" type="string">
  Inclusive start of the effective usage period as an ISO 8601 timestamp.
</ResponseField>

<ResponseField name="end" type="string">
  Exclusive end of the effective usage period as an ISO 8601 timestamp.
</ResponseField>

<ResponseField name="jurisdictions" type="array">
  Jurisdictions with non-zero usage that are available to your account.

  <Expandable title="Jurisdiction usage fields">
    <ResponseField name="jurisdiction" type="string">
      Two-letter jurisdiction code, such as `BE`, `GB`, `US`, or `EU`.
    </ResponseField>

    <ResponseField name="name" type="string">
      Display name of the jurisdiction.
    </ResponseField>

    <ResponseField name="source_search_count" type="integer">
      Number of source searches attributed to the jurisdiction.
    </ResponseField>

    <ResponseField name="report_count" type="integer">
      Number of reports attributed to the jurisdiction.
    </ResponseField>

    <ResponseField name="total_usage" type="integer">
      Sum of `source_search_count` and `report_count` for the jurisdiction.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="total_usage" type="integer">
  Sum of usage across all returned jurisdictions.
</ResponseField>

<ResponseExample>
  ```json Example response theme={null}
  {
    "user_id": 123,
    "start": "2026-09-01T00:00:00Z",
    "end": "2026-10-01T00:00:00Z",
    "jurisdictions": [
      {
        "jurisdiction": "BE",
        "name": "Belgium",
        "source_search_count": 7,
        "report_count": 2,
        "total_usage": 9
      }
    ],
    "total_usage": 9
  }
  ```
</ResponseExample>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://parsagon.io/api/usage/v1/jurisdictions/?start=2026-09-01T00:00:00Z&end=2026-10-01T00:00:00Z" \
    -H "Authorization: Token YOUR_API_KEY_HERE"
  ```
</RequestExample>


# List searches
Source: https://docs.parsagon.io/api-reference/endpoint/list-searches

GET https://parsagon.io/api/events/v1/search/
Retrieve a list of all searches made on your account, including both Quick Searches and Advanced Searches.

Returns all searches associated with your account, ordered from most recent to oldest. Both Quick Searches and Advanced Searches appear in this list and count equally toward your quota.

## Response

<ResponseField name="results" type="array">
  Array of Search objects.

  <Expandable title="Search object fields">
    <ResponseField name="id" type="number | string">
      Unique identifier for the Search.
    </ResponseField>

    <ResponseField name="categories" type="array">
      Array of category IDs used in the search.
    </ResponseField>

    <ResponseField name="context" type="string">
      Context provided in the request.
    </ResponseField>

    <ResponseField name="filter_prompt" type="string">
      Filter prompt provided in the request.
    </ResponseField>

    <ResponseField name="labels" type="object">
      Labels provided in the request.
    </ResponseField>

    <ResponseField name="date_range" type="object">
      The date range used, containing either `start_date` and `end_date`, or `duration_seconds`.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      Timestamp when the Search was created (ISO 8601, UTC).
    </ResponseField>

    <ResponseField name="error" type="string | null">
      Error message if the search failed; otherwise `null`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json Example response theme={null}
  {
    "count": 844,
    "next": "https://parsagon.io/api/events/v1/search/?limit=10&offset=10",
    "previous": null,
    "results": [
      {
        "id": 4973,
        "categories": [2282],
        "context": "User is a Government Relations Manager for a fintech company in Germany",
        "filter_prompt": "Regulations and policies related to financial technology (fintech) industry development and oversight in Germany\nData privacy and cybersecurity laws impacting fintech companies, including compliance with GDPR and other data protection standards",
        "date_range": {"duration_seconds": 604800, "end_date": null},
        "created_at": "2026-03-25T12:55:13.665178Z",
        "error": null,
        "labels": {}
      },
      ...
    ]
  }
  ```
</ResponseExample>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://parsagon.io/api/events/v1/search/" \
    -H "Authorization: Token YOUR_API_KEY_HERE"
  ```
</RequestExample>


# List transcripts
Source: https://docs.parsagon.io/api-reference/endpoint/list-transcripts

GET https://parsagon.io/api/transcripts/v1/categories/{category}/transcripts
Retrieve a paginated list of transcripts within a specified category.

Results are paginated and include summary information for each transcript. To retrieve the full transcript text for a given transcript, use the [get transcript](/api-reference/endpoint/get-transcript) endpoint.

## Path parameters

<ParamField type="string">
  The transcript category to list transcripts from.
</ParamField>

## Response

Returns a paginated response containing transcript summary objects.

<ResponseField name="count" type="integer">
  Total number of transcripts matching the query.
</ResponseField>

<ResponseField name="next" type="string">
  URL for the next page of results, or `null` if there are no more pages.
</ResponseField>

<ResponseField name="previous" type="string">
  URL for the previous page of results, or `null` if this is the first page.
</ResponseField>

<ResponseField name="results" type="array">
  List of transcript summary objects.

  <Expandable title="Result fields">
    <ResponseField name="id" type="string">
      Unique identifier for the transcript.
    </ResponseField>

    <ResponseField name="title" type="string">
      Title of the transcript.
    </ResponseField>

    <ResponseField name="scheduled_time" type="string">
      Scheduled time of the event in ISO 8601 format.
    </ResponseField>

    <ResponseField name="url" type="string">
      URL of the original audio or video source.
    </ResponseField>

    <ResponseField name="transcript_status" type="string">
      Current status of the transcript.
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://parsagon.io/api/transcripts/v1/categories/2/transcripts/" \
    -H "Authorization: Token YOUR_API_KEY_HERE"
  ```
</RequestExample>

<ResponseExample>
  ```json Example response theme={null}
  {
    "count": 17,
    "next": "https://parsagon.io/api/transcripts/v1/categories/2/transcripts/?limit=10&offset=10",
    "previous": null,
    "results": [
      {
        "id": 5103756,
        "title": "Committee on Civil Liberties, Justice and Home Affairs Ordinary meeting",
        "scheduled_time": "2026-05-07T07:30:00Z",
        "url": "https://multimedia.europarl.europa.eu/en/webstreaming/committee-on-civil-liberties-justice-and-home-affairs-ordinary-meeting_20260507-0900-COMMITTEE-LIBE",
        "transcript_status": "FINISHED"
      },
      {
        "id": 5103754,
        "title": "Committee on the Internal Market and Consumer Protection Ordinary meeting",
        "scheduled_time": "2026-05-07T07:00:00Z",
        "url": "https://multimedia.europarl.europa.eu/en/webstreaming/committee-on-internal-market-and-consumer-protection-ordinary-meeting_20260507-0900-COMMITTEE-IMCO",
        "transcript_status": "FINISHED"
      },
      ...
    ]
  }
  ```
</ResponseExample>


# Quick Search
Source: https://docs.parsagon.io/api-reference/endpoint/quick-search

POST https://parsagon.io/api/events/v1/quick-search/
Execute a search and receive results immediately, without needing to poll a persistent Search object for completion.

The Quick Search endpoint runs a search synchronously and returns results directly in the response. A Search object is still created and counts toward your quota, but unlike Advanced Search you don't need to poll for results — they're returned immediately.

## Request body

<ParamField type="array">
  Array of category IDs to include in the search results.
</ParamField>

<ParamField type="string">
  Additional context for the AI to tailor the search and reporting (for example, your organization or focus area). Maximum 1000 characters.
</ParamField>

<ParamField type="string">
  A list of policy topics to search for, one per line. Longer, descriptive phrases work best. Maximum 5000 characters.
</ParamField>

<ParamField type="object">
  A dictionary of string key-value pairs for your own record keeping. Use this to attach metadata to the search, such as the project or team it belongs to (for example, `{"project": "tax-reform", "team": "policy"}`).
</ParamField>

<ParamField type="boolean">
  Set to `true` to validate the request and return example data without running a source search. Required fields such as `categories`, `filter_prompt`, and `date_range` are still validated normally.
</ParamField>

<ParamField type="object">
  Custom dummy data to return when `is_test` is `true`. Quick Search only supports custom `search_results`; it does not support custom edited outputs.

  <Expandable title="Test data fields">
    <ParamField type="array">
      Array of search result objects to return instead of Parsagon's built-in example results.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object">
  Time period to search within. Must cover no more than **72 hours (3 days)** — use either `start_date`/`end_date` or `duration_seconds` ≤ 259200.

  <Expandable title="Fixed range">
    <ParamField type="string">
      ISO 8601 datetime (UTC). The earliest supported value is 90 days before the time of the request.
    </ParamField>

    <ParamField type="string">
      ISO 8601 datetime (UTC).
    </ParamField>
  </Expandable>

  <Expandable title="Relative duration">
    <ParamField type="number">
      Positive number of seconds before "now" to search within (maximum 259200).
    </ParamField>
  </Expandable>
</ParamField>

## Response

<ResponseField name="search_results" type="array">
  Array of search result objects.

  <Expandable title="Search result fields">
    <ResponseField name="url" type="string">
      URL of the source document.
    </ResponseField>

    <ResponseField name="title" type="string">
      Title of the document.
    </ResponseField>

    <ResponseField name="date" type="string">
      Date when Parsagon collected the document (ISO 8601, UTC). This may differ slightly from the original publication date.
    </ResponseField>

    <ResponseField name="text" type="string">
      Full text (or main body) of the document.
    </ResponseField>

    <ResponseField name="summary" type="string">
      AI-generated 1–2 sentence summary of the document.
    </ResponseField>

    <ResponseField name="type" type="string">
      Type of document. Either `"ARTICLE"` (press releases, announcements, generic articles, and similar content) or `"LAW"` (bills and legislation).
    </ResponseField>

    <ResponseField name="extra_data" type="object">
      For `"LAW"` documents, an object containing additional legislative metadata. May include `status`, `last_action`, and `last_action_date` — not all fields are present on every document. For non-`"LAW"` documents, this is usually empty.
    </ResponseField>

    <ResponseField name="search_topics" type="array">
      List of integers, each being the zero-based index of a line in `filter_prompt` that is relevant to this search result.
    </ResponseField>

    <ResponseField name="jurisdictions" type="array">
      List of jurisdictions that apply to this result.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="error" type="string | null">
  Error message if an error occurred; otherwise `null`.
</ResponseField>

<ResponseField name="is_test" type="boolean">
  Whether the Search was created in test mode.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://parsagon.io/api/events/v1/quick-search/" \
    -H "Authorization: Token YOUR_API_KEY_HERE" \
    -H "Content-Type: application/json" \
    -d '{
      "categories": [34],
      "context": "User is a medical association",
      "filter_prompt": "Healthcare policy and regulatory developments impacting health insurers and healthcare providers\nLegislation related to insurance mandates, consumer protections, and healthcare affordability",
      "date_range": {
        "start_date": "2026-02-02T08:00",
        "end_date": "2026-02-04T08:00"
      }
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json Example response theme={null}
  {
    "search_results": [
      {
        "url": "https://legislature.maine.gov/LawMakerWeb/summary.asp?ID=280101474",
        "title": "An Act to Lower Health Insurance Costs, Reduce Barriers to Health Care and Ensure Fair Prices for Health Care",
        "text": "Be it enacted by the People of the State of Maine as follows:...",
        "summary": "This act aims to lower health insurance costs, reduce barriers to health care, and ensure fair prices for health care services in Maine.",
        "date": "2026-02-03",
        "type": "LAW",
        "extra_data": {
          "last_action": "Committee on Health Coverage, Insurance and Financial Services suggested and ordered printed. The Bill was REFERRED to the Committee on HEALTH AND HUMAN SERVICES.",
          "last_action_date": "2/3/2026"
        },
        "search_topics": [0],
        "jurisdictions": ["US Maine"]
      }
    ],
    "error": null,
    "is_test": false
  }
  ```
</ResponseExample>

## Test mode

Use `is_test: true` to test your integration without running a source search. The endpoint still validates the request body the same way it does for a normal Quick Search request.

```json Example test request body theme={null}
{
  "categories": [34],
  "context": "User is a medical association",
  "filter_prompt": "Healthcare policy and regulatory developments",
  "date_range": {
    "duration_seconds": 86400
  },
  "is_test": true,
  "test_data": {
    "search_results": [
      {
        "url": "https://example.com/policy-update",
        "title": "Example policy update",
        "text": "Example source text for testing.",
        "summary": "Example summary returned in test mode.",
        "date": "2026-02-03",
        "type": "ARTICLE",
        "extra_data": {},
        "search_topics": [0],
        "jurisdictions": ["US Maine"]
      }
    ]
  }
}
```


# Search transcripts
Source: https://docs.parsagon.io/api-reference/endpoint/search-transcripts

GET https://parsagon.io/api/transcripts/v1/categories/{category}/search
Search through transcripts within a specified category and date range.

The search runs over both completed and partial (in-progress) transcripts. Note that partial transcripts often lag livestreams by approximately 30 minutes or more.

## Path parameters

<ParamField type="string">
  The transcript category to search within.
</ParamField>

## Query parameters

<ParamField type="string">
  Search query string. Supports standard web search syntax, including:

  * **Exact phrases** — wrap in quotes (e.g., `"phrase one"`)
  * **Boolean operators** — combine terms with `OR` (e.g., `one OR two`)
  * **Excluded words** — prefix with `-` (e.g., `-phrase`)

  Search terms automatically match different grammatical forms (e.g., searching for "run" also matches "running" and "ran").
</ParamField>

<ParamField type="string">
  Start of the date range to search within (ISO 8601 format). The date range between `start_date` and `end_date` must not exceed one week.
</ParamField>

<ParamField type="string">
  End of the date range to search within (ISO 8601 format). The date range between `start_date` and `end_date` must not exceed one week.
</ParamField>

## Response

Returns a list of transcript summary objects matching the search criteria, with highlighted keyword matches.

<ResponseField name="results" type="array">
  List of transcript summary objects matching the query.

  <Expandable title="Result fields">
    <ResponseField name="id" type="string">
      Unique identifier for the transcript.
    </ResponseField>

    <ResponseField name="title" type="string">
      Title of the transcript.
    </ResponseField>

    <ResponseField name="scheduled_time" type="string">
      Scheduled time of the event in ISO 8601 format.
    </ResponseField>

    <ResponseField name="url" type="string">
      URL of the original audio or video source.
    </ResponseField>

    <ResponseField name="transcript_status" type="string">
      Current status of the transcript.
    </ResponseField>

    <ResponseField name="headline" type="string">
      Excerpt from the transcript with matching search terms highlighted in bold.
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://parsagon.io/api/transcripts/v1/categories/2/search/?q=consumer&start_date=2026-05-07&end_date=2026-05-08" \
    -H "Authorization: Token YOUR_API_KEY_HERE"
  ```
</RequestExample>

<ResponseExample>
  ```json Example response theme={null}
  {
    "results": [
      {
        "id": 5103756,
        "title": "Committee on Civil Liberties, Justice and Home Affairs Ordinary meeting",
        "scheduled_time": "2026-05-07T07:30:00Z",
        "url": "https://multimedia.europarl.europa.eu/en/webstreaming/committee-on-civil-liberties-justice-and-home-affairs-ordinary-meeting_20260507-0900-COMMITTEE-LIBE",
        "transcript_status": "FINISHED",
        "headline": "... caps requirements through targeted amendments of the GDPR record-keeping obligation, the digital omnibus with targeted amendments to the GDPR. And furthermore, I initiated my first three implementation dialogues on the simplification of **consumer** law in the digital environment  the GDPR, and only yesterday on the revision of the **Consumer** Protection Cooperation Regulation. So thank you, Chair and Honourable Members, for your attention, and thank you for your continued support ..."
      },
      ...
    ]
  }
  ```
</ResponseExample>


# Transcript requests
Source: https://docs.parsagon.io/api-reference/endpoint/transcript-requests

Request a transcript for a public audio or video URL, check processing status, and assign speaker names.

Transcript requests let you submit a public audio or video URL for transcription. Parsagon records the source, transcribes it, diarizes speakers, and returns the completed transcript through the API.

Hearings and debates are often several hours long, so transcription can take a few hours to complete.

## Workflow

<Steps>
  <Step title="Create a transcript request">
    Submit the public source URL with `POST /api/transcripts/v1/requests/`.
  </Step>

  <Step title="Poll the request">
    Use `GET /api/transcripts/v1/requests/{id}/` until `status` is `FINISHED` or `ERROR`. Poll about every 15 minutes.
  </Step>

  <Step title="Assign speaker names, if needed">
    After the transcript is finished, send speaker profiles to `POST /api/transcripts/v1/requests/{id}/assign-speakers/`.
  </Step>
</Steps>

## Create a request

```http theme={null}
POST https://parsagon.io/api/transcripts/v1/requests/
```

Use this endpoint to submit a public URL for transcription. The response includes an `id`; use that ID to poll status and assign speaker names.

<ParamField type="string">
  Public `https://` URL for the audio or video source to transcribe.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://parsagon.io/api/transcripts/v1/requests/" \
    -H "Authorization: Token YOUR_API_KEY_HERE" \
    -H "Content-Type: application/json" \
    -d '{
      "url": "https://example.gov/hearings/sample-public-meeting"
    }'
  ```
</RequestExample>

## Get request status and results

```http theme={null}
GET https://parsagon.io/api/transcripts/v1/requests/{id}/
```

Use this endpoint to check processing status and retrieve transcript output when it is ready.

Transcription can take a few hours for long hearings or debates. Poll this endpoint about every 15 minutes rather than making frequent status requests.

<ParamField type="string">
  Transcript request ID returned when you created the request. This ID is a UUID-formatted string.
</ParamField>

<ResponseField name="id" type="string">
  Unique transcript request ID. This ID is a UUID-formatted string.
</ResponseField>

<ResponseField name="url" type="string">
  Original URL submitted for transcription.
</ResponseField>

<ResponseField name="source" type="integer">
  Internal source ID associated with the transcript data.
</ResponseField>

<ResponseField name="title" type="string">
  Title detected for the source, when available.
</ResponseField>

<ResponseField name="status" type="string">
  Request-level status. Possible values include `QUEUED`, `RECORDING`, `TRANSCRIBING`, `DIARIZING`, `FINISHED`, `ERROR`, and `CANCELED`.
</ResponseField>

<ResponseField name="transcript_status" type="string">
  Source-level transcript processing status.
</ResponseField>

<ResponseField name="text" type="string">
  Full transcript text. This is available when transcription has completed. If speaker names have been assigned, the text uses the assigned names.
</ResponseField>

<ResponseField name="extra_data" type="object">
  Structured transcript data.

  <Expandable title="extra_data fields">
    <ResponseField name="segments" type="array">
      Segment-level transcript data.

      <Expandable title="Segment fields">
        <ResponseField name="start" type="number">
          Start time of the segment in seconds, when available.
        </ResponseField>

        <ResponseField name="end" type="number">
          End time of the segment in seconds, when available.
        </ResponseField>

        <ResponseField name="text" type="string">
          Transcribed text for this segment.
        </ResponseField>

        <ResponseField name="speaker" type="string">
          Speaker label or assigned speaker name for this segment.
        </ResponseField>

        <ResponseField name="speaker_profile" type="object">
          Speaker profile attached after speaker assignment.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="speaker_profiles" type="array">
  Speaker profiles currently stored on the request.
</ResponseField>

<ResponseField name="error" type="string">
  Error message if the request failed.
</ResponseField>

<ResponseField name="created_at" type="string">
  Time the request was created in ISO 8601 format.
</ResponseField>

<ResponseField name="updated_at" type="string">
  Time the request was last updated in ISO 8601 format.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://parsagon.io/api/transcripts/v1/requests/2fb8ec8f-6d55-4f5d-91e5-89ce6f617d58/" \
    -H "Authorization: Token YOUR_API_KEY_HERE"
  ```
</RequestExample>

<ResponseExample>
  ```json Example response theme={null}
  {
    "id": "2fb8ec8f-6d55-4f5d-91e5-89ce6f617d58",
    "url": "https://example.gov/hearings/sample-public-meeting",
    "source": 5104001,
    "title": "Sample public meeting",
    "status": "FINISHED",
    "transcript_status": "FINISHED",
    "text": "Jane Doe:\nGood evening, everyone...",
    "extra_data": {
      "segments": [
        {
          "start": 12.4,
          "end": 26.8,
          "speaker": "Jane Doe",
          "speaker_profile": {
            "profile_id": "jane-doe",
            "name": "Jane Doe"
          },
          "text": "Good evening, everyone..."
        }
      ]
    },
    "speaker_profiles": [
      {
        "id": "jane-doe",
        "name": "Jane Doe",
        "aliases": ["Committee Chair", "District One Representative"]
      }
    ],
    "error": "",
    "created_at": "2026-07-10T15:10:00Z",
    "updated_at": "2026-07-10T15:45:00Z"
  }
  ```
</ResponseExample>

## List your requests

```http theme={null}
GET https://parsagon.io/api/transcripts/v1/requests/
```

Returns a paginated list of transcript requests created by your account.

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://parsagon.io/api/transcripts/v1/requests/" \
    -H "Authorization: Token YOUR_API_KEY_HERE"
  ```
</RequestExample>

## Assign speaker names

```http theme={null}
POST https://parsagon.io/api/transcripts/v1/requests/{id}/assign-speakers/
```

Use this endpoint after `status` is `FINISHED` to map transcript speaker labels to the people you provide in `speaker_profiles`.

<ParamField type="string">
  Transcript request ID returned when you created the request. This ID is a UUID-formatted string.
</ParamField>

<ParamField type="array">
  List of speaker profiles to assign.

  <Expandable title="Speaker profile fields">
    <ParamField type="string">
      Stable identifier for the speaker profile. If your system uses numeric IDs, send them as strings.
    </ParamField>

    <ParamField type="string">
      Display name for the speaker. Each profile must include either `id` or `name`.
    </ParamField>

    <ParamField type="array">
      Optional names, titles, or transcript variants that may refer to the same person.
    </ParamField>
  </Expandable>
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://parsagon.io/api/transcripts/v1/requests/2fb8ec8f-6d55-4f5d-91e5-89ce6f617d58/assign-speakers/" \
    -H "Authorization: Token YOUR_API_KEY_HERE" \
    -H "Content-Type: application/json" \
    -d '{
      "speaker_profiles": [
        {
          "id": "jane-doe",
          "name": "Jane Doe",
          "aliases": ["Committee Chair", "District One Representative"]
        },
        {
          "id": "john-doe",
          "name": "John Doe",
          "aliases": ["Dr. Doe", "Planning Director"]
        }
      ]
    }'
  ```
</RequestExample>

## Speaker profile guidance

Use stable string IDs and include aliases that may appear in the transcript.

```json Example speaker profiles theme={null}
{
  "speaker_profiles": [
    {
      "id": "alex-example",
      "name": "Alex Example",
      "aliases": ["Vice Chair", "District Two Representative"]
    },
    {
      "id": "sam-sample",
      "name": "Sam Sample",
      "aliases": ["Dr. Sample", "Public Works Director", "Project Lead"]
    }
  ]
}
```

<Tip>
  Include roles, titles, honorifics, and alternate names as aliases. Speaker profile IDs must be strings, even if they come from numeric IDs in your system.
</Tip>


# Introduction
Source: https://docs.parsagon.io/api-reference/introduction

Programmatically retrieve political monitoring data and AI-generated monitoring reports using the Parsagon Search API.

## Overview

The Parsagon Search API gives you programmatic access to a daily-updated dataset of legislation, regulations, and other government publications across 70+ countries.

We currently have active coverage for the following countries:

Argentina, Australia, Austria, Belgium, Brazil, Bulgaria, Canada, Chile, China, Colombia, Costa Rica, Croatia, Cyprus, Czech Republic, Denmark, Dominican Republic, Ecuador, Egypt, Estonia, European Union, Finland, France, Germany, Greece, Hong Kong, Hungary, India, Indonesia, Ireland, Israel, Italy, Japan, Kazakhstan, Kenya, Kuwait, Latvia, Lithuania, Malaysia, Malta, Mexico, Netherlands, New Zealand, Nigeria, Norway, Peru, Philippines, Poland, Portugal, Qatar, Romania, Saudi Arabia, Singapore, Slovakia, Slovenia, South Africa, South Korea, Spain, Sweden, Switzerland, Taiwan, Thailand, Turkey, Turkmenistan, Ukraine, United Arab Emirates, United Kingdom, United States, Uruguay, Uzbekistan, Vietnam

If you need coverage for a jurisdiction we don't currently list, we can typically add it quickly.

We can ingest and deliver essentially any publicly available government material (where available in a jurisdiction), including:

* Legislation
* Regulations
* Consultations
* Guidance
* Enforcement actions
* Press releases and announcements
* Speeches
* Mainstream business/political news

## Methods

The API provides three ways to retrieve data:

**Quick Search** runs an ad-hoc search and returns results immediately. Use this for one-off queries over a window of up to 72 hours. No persistent object is created.

**Advanced Search** creates a persistent Search object and processes it asynchronously. It supports date ranges up to 90 days and can produce an AI-generated report alongside raw results. Poll the returned `id` to retrieve results once processing is complete.

**Get Category Sources** returns the full chronological list of all sources collected for a given data category, without any AI filtering or summarization. Use this to retrieve raw, unfiltered data for a specific category, covering up to the last 90 days.

## Base URL

All endpoints are relative to:

```text theme={null}
https://parsagon.io/api/events/v1/
```

## Authentication

All requests must be authenticated using an API key.

Include your API key in the `Authorization` HTTP header, prefixed with `Token` and a space:

```http theme={null}
Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b
```

You can view and manage your API key by logging into Parsagon and visiting your [settings](https://parsagon.io/settings) page.

## Content types

Request bodies must be sent as JSON:

```http theme={null}
Content-Type: application/json
```

Responses are returned as JSON.

## Shared request schema

Both **Quick Search** and **Advanced Search** use the same request body schema.

<ParamField type="array">
  Array of category IDs to include in the search results.
</ParamField>

<ParamField type="string">
  Additional context for the AI to tailor the search and reporting (for example, your organization or focus area). Maximum 1000 characters.
</ParamField>

<ParamField type="string">
  A description of what to search for. This should be a list of policy topics, one per line — longer, descriptive phrases work best. Maximum 5000 characters.

  ```text Example filter_prompt theme={null}
  Government funding and subsidies for aerospace R&D innovation
  Workforce development and skills programs for aerospace manufacturing, engineering, and skilled labour
  Regulations governing aviation safety, environmental impact, and emissions standards
  ```
</ParamField>

<ParamField type="boolean">
  Set to `true` to validate the request without running a source search. Quick Search returns example data immediately. Advanced Search creates a dummy Search object; retrieve it with Get Search to read the dummy data. Required fields such as `categories`, `filter_prompt`, and `date_range` are still validated normally.
</ParamField>

<ParamField type="object">
  Optional dummy data to use when `is_test` is `true`. If omitted, Parsagon returns built-in example search results.

  <Expandable title="Test data fields">
    <ParamField type="array">
      Custom search results to use instead of the built-in examples.
    </ParamField>

    <ParamField type="any">
      Custom edited output for Advanced Search. Quick Search does not support `edited_results`.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object">
  Constrains the time period for documents. Specify either a fixed range (`start_date` and `end_date`) or a relative duration (`duration_seconds`).

  <Expandable title="Fixed range">
    <ParamField type="string">
      ISO 8601 datetime (UTC). The earliest supported value is 90 days before the time of the request.
    </ParamField>

    <ParamField type="string">
      ISO 8601 datetime (UTC).
    </ParamField>
  </Expandable>

  <Expandable title="Relative duration">
    <ParamField type="number">
      Positive number of seconds before "now" to search within.
    </ParamField>
  </Expandable>
</ParamField>

### Date range limits

| Endpoint        | Maximum window                                  |
| --------------- | ----------------------------------------------- |
| Quick Search    | 72 hours (3 days) — `duration_seconds` ≤ 259200 |
| Advanced Search | 90 days — `duration_seconds` ≤ 7776000          |

For all search types, the earliest supported `start_date` is **90 days** before the time of the request. Historical data older than 90 days is available upon request.

**Example request body:**

```json theme={null}
{
  "categories": [1, 2],
  "context": "User is a Government Relations Manager for an aerospace company in the UK.",
  "filter_prompt": "Government funding and subsidies for aerospace R&D innovation\nWorkforce development and skills programs for aerospace manufacturing, engineering, and skilled labour\nRegulations governing aviation safety, environmental impact, and emissions standards",
  "date_range": {
    "duration_seconds": 259200
  }
}
```

## Test mode

Use `is_test: true` to test request validation and response handling without running a source search or report generation task.

* Quick Search can return built-in example `search_results` or custom `test_data.search_results`.
* Advanced Search returns a dummy Search object. Use its `id` with Get Search to retrieve built-in example `search_results`, custom `test_data.search_results`, and custom `test_data.edited_results`.
* Create Report returns a dummy Report object with built-in example `result` data or custom `test_data.result`.
* `test_data` can only be used when `is_test` is `true`.
* Required fields are still validated normally. For Search endpoints, this includes `categories`, `filter_prompt`, and `date_range`. For Create Report, this includes `topic`, `structure`, `audience`, and `length`.

```json Example test request body theme={null}
{
  "categories": [1],
  "context": "User is testing an API integration.",
  "filter_prompt": "Example policy updates",
  "date_range": {
    "duration_seconds": 86400
  },
  "is_test": true,
  "test_data": {
    "search_results": [
      {
        "url": "https://example.com/policy-update",
        "title": "Example policy update",
        "summary": "Example summary returned in test mode.",
        "date": "2026-02-03",
        "type": "ARTICLE"
      }
    ]
  }
}
```

```json Example report test request body theme={null}
{
  "topic": "Financial services regulatory developments in the UK",
  "structure": "Executive summary, key developments, and implications",
  "audience": "Government relations team",
  "length": "SHORT_MEMO",
  "is_test": true,
  "test_data": {
    "result": {
      "text": "# Example report\n\nExample report content returned in test mode.",
      "html": "<h1>Example report</h1><p>Example report content returned in test mode.</p>",
      "type": "html"
    }
  }
}
```