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 Search API.
---

# Parsagon Search API

Use this skill when code interacts with the Parsagon Search 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** (`GET /categories/{category_id}/sources/`) when the integration needs raw chronological source material for a category without AI filtering or summarization.

Use **Get Category Sources** to retrieve a comprehensive list of sources for a category. Results are paginated and chronological, oldest first. The response includes `count`, `next`, `previous`, and `results`. Results cover up to the last 90 days, but some categories may have less than 90 days available.

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.

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.

## 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.

Required fields such as `categories`, `filter_prompt`, and `date_range` are still validated in test mode.

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.

```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"
      }
    ]
  }
}
```

## 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.

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