Coding agent skill

.agents/skills/parsagon-api/

.claude/skills/parsagon-api/

---
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
```