Reports

Append sections to an existing report

Adds sections to a report that already exists, with the same composition vocabulary /v1/reports/create takes. A section is either catalog -- a section of a published entry, named by its slug and its 0-based position -- or custom, whose widgets are written as DSL. This is NOT the vocabulary of the AI assistant of the app: nothing here is natural language. A widget of a custom section whose dsl has visualization: text is a block of prose: it reads no data, so it carries no integration_id, the empty value of every data key and its Markdown in content. A section of an append carries add_summary and show_previous_period like a section of a creation, and the summary OF A SECTION is accepted here -- what an append does not write is the summary of the whole report. It spends AI credits of the account when the report is opened, viewed or delivered by a schedule, never when it is written. Two kinds of report cannot receive sections and answer 400 APPEND_NOT_ALLOWED with details.reason: a template_based report, whose sections are its template's, and a report whose widgets each carry their own connection. That second one takes an append when every widget of the body that reads data brings its connection_key and account_id; a widget whose dsl compares connected accounts brings them in compare.items instead and needs no pair of its own. This endpoint accepts if_version. Refusals: 400 VALIDATION_FAILED, UNKNOWN_PARAM or APPEND_NOT_ALLOWED, 403 WRITE_ACCESS_DISABLED, 404 NOT_FOUND for the report and TEMPLATE_NOT_FOUND for a catalog section that is no longer published, 409 VERSION_MISMATCH with details {expected, actual} plus the idempotency conflicts. The 403 of this endpoint is only ever WRITE_ACCESS_DISABLED: adding sections to a report that already exists does not spend a unit of the plan, so PLAN_LIMIT_REACHED belongs to the two endpoints that create a report. This endpoint never asks for a confirmation, so it never answers CONFIRMATION_EXPIRED or CONFIRMATION_MISMATCH. The undo of an append is deleting the sections it created.

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

post/reports/append

Request

  • Base URL: https://api.reportingninja.com/v1
  • URL: https://api.reportingninja.com/v1/reports/append
  • Auth: HTTP bearer

Request body

report_keystring required

The report the sections are added to.

language'en' | 'es'

Language of the literals of the new sections. Defaults to the account owner's.

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.

if_versionnumber

The version of the report's sections structure this call expects. A mismatch is HTTP 409 VERSION_MISMATCH and nothing is written.

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.