Add a section to a report

Adds one empty section at the END of a report and raises the version of its sections structure.

The section is born with the defaults of the product -- the date range a new section gets, the flags of its header, its page orientation and every global filter set to none -- which are the same ones every section of a new report is created with. Only name and page_break are asked for; everything else is changed afterwards with /v1/sections/update.

IT GOES AT THE END and there is no way to ask for another position, which is what the application offers too: move it with /v1/sections/reorder. It starts EMPTY -- widgets go in with /v1/widgets/create, or a whole section with its widgets is written in one call with /v1/reports/append.

There is no ceiling on the sections of a report. It accepts if_version and answers the new one.

A report built on a template is refused with 400 APPEND_NOT_ALLOWED, reason template_based: its sections belong to its template.

Refusals: 400 for the framework and the body, 400 VALIDATION_FAILED, 400 APPEND_NOT_ALLOWED, 403 WRITE_ACCESS_DISABLED, 404 NOT_FOUND, 409 VERSION_MISMATCH and 409 REPORT_IN_TRASH.

Every write endpoint reads dry_run and idempotency_key; see the Write guarantees section of the introduction.

post/sections/create

Request

Base URL: https://api.reportingninja.com/v1
URL: https://api.reportingninja.com/v1/sections/create
Auth: HTTP bearer

Request body

report_keystring required

The report the section goes into.

namestring required

The title of the section, 1 to 80 characters, with no character above the Basic Multilingual Plane (an emoji, most often).

page_breakboolean

Whether the PDF starts a new page at this section. Default true, which is what the application proposes for a new section.

if_versioninteger

The sections version of the report, as /v1/reports/get publishes it. A stale one is HTTP 409 VERSION_MISMATCH.

dry_runboolean

Validate and answer what WOULD happen, without writing anything. Default false.

idempotency_keystring

Makes a retry safe: the answer of the first call is replayed for 24 hours to any later call with the same key and the same body.

Response

The call succeeded. This endpoint reports its errors with a real HTTP status, so a 200 always carries status=ok.

status'ok' required

Changes

No recorded changes to this operation across all 1 revision of this API.