Create report

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"
  }'

{
  "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
}

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"
  }'

{
  "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
}

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

string

required

Topic for the report. Maximum 1000 characters.

string

required

Instructions for the report structure. Maximum 5000 characters.

string

required

Intended audience for the report. Maximum 1000 characters.

string

required

Approximate report length. Must be one of SHORT_MEMO, EXEC_MEMO, MID_REPORT, or LONG_REPORT.

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.

object

Custom dummy data to store when is_test is true. Use this to test downstream handling of report results.

Show Test data fields

object

Custom report result to store instead of Parsagon’s built-in example result. This value is stored exactly as provided.

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.

number | string

Unique identifier for the Report. Use this to retrieve results.

string

Report type. For this endpoint, the value is BRIEF.

object

Stored request fields, including topic, structure, audience, and numeric target length.

string

Timestamp when the Report was created (ISO 8601, UTC).

string | null

Timestamp when report generation finished, or null while processing.

object | null

Generated report content when processing is complete, or dummy report content in test mode.

number

Processing progress from 0 to 100.

string | null

Error message if report generation failed; otherwise null.

string

Public UUID for the Report.

boolean

Whether the Report was created in test mode.

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"
  }'

{
  "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
}

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.

Example test request body

{
  "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"
    }
  }
}

Example test response

{
  "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
}

Overview

Endpoints

AI tools

Request body

Response

Test mode

​Request body

​Response

​Test mode

Request body

Response

Test mode