Create a report share link

Creates a share link for a report run with an optional label, expiry time or never-expire setting.

POST https://app.upfour.io/v1/reports/{runID}/share

A real request. Sending it changes data in your up4 account.

Authorization

AuthorizationA pls_ key. It stays in this browser tab. Needs report.write.

Path

runIDpath · requiredPart of the request path.

Body

More fields3

expires_at When the link stops working. Without it and without never_expires the link works for 90 days. label A note for yourself; shown in the list of links.

never_expires A link without an end. Cannot be combined with expires_at.

Headers

Idempotency-KeyheaderGenerated automatically when empty. How it works

Sent directly from your browser to https://app.upfour.io/v1. Mutating calls get an automatic Idempotency-Key when the field is empty.

Request

Responsenot sent yet

Fill in a key and press Send request (⌘↵).
The answer appears here.

scope report.write stable Idempotency-Key supported returns 201

Parameters

Field	Type	Description
`runID` required	uuid	path parameter

Body

application/json optional 3 fields

All other fields3 fields

expires_atstring (date-time) · nullable

When the link stops working. Without it and without never_expires the link works for 90 days.

labelstring

A note for yourself; shown in the list of links.

never_expiresboolean

A link without an end. Cannot be combined with expires_at.

Returns

A successful request returns 201 with application/json.

Response fields 1 top-level fields

Field Type Description

data ReportShareLinkCreated

ReportShareLinkCreated · 17 fields

Field Type Description

link ReportShareLink

ReportShareLink · 14 fields

Field	Type	Description
`created_at`	string (date-time)
`id`	uuid
`label`	string
`organization_id`	uuid
`report_run_id`	uuid
`view_count`	integer
`client_id`	uuid
`created_by`	uuid
`expires_at`	string (date-time)	Absent for a link that never expires.
`format`	string one of`csvjsonpdfxlsx`
`range_from`	string (date-time)
`range_to`	string (date-time)
`report_type`	string one of`executive_summarysummarymonitor_reportmonitorsmonitor_slaslaincident_analyticsincidentsresponse_timeresponse-timedowntime_ledgerdowntime-ledgertrends`
`revoked_at`	string (date-time)

token string The secret part of the link; shown only in this answer.

url string The public link of the snapshot, on the Company's report domain when one is set.

Errors

Only the errors this operation can return. Every error uses the same envelope.

Status	Code	Meaning
400	`bad_request`	The request is malformed or fails validation.
402	`billing_action_unavailable`	The Company's billing state does not allow this action. When: A metered or limited action while the billing state, such as paused or without credit, blocks it; details holds the action and billing_state. Fix: Top up the credit or change the plan, then retry.
409	`conflict`	The request conflicts with the current state.
404	`not_found`	The requested resource does not exist or is outside the caller's scope.
403	`permission_denied`	The credentials do not permit this action.
503	`quota_gate_unavailable`	The limit check itself failed, so the action was not carried out. When: The quota service could not decide while the request ran. Fix: Retry in a moment; nothing was changed.
403 / 429	`quota_limit_reached`	A usage or inventory limit of the Company was reached. When: Counters and concurrency limits answer 429 with Retry-After, inventory and capacity limits answer 403; details holds purpose, limit and window. Fix: On 429 wait Retry-After seconds; on 403 free something up, request a higher limit where details.raise_request is true, or buy an extension.
503	`service_unavailable`	The service or a required dependency is temporarily unavailable.

Every call can also return unauthorized (401), rate_limit_exceeded (429) or internal_error (500 / 502). See Responses and errors.

curl -s -X POST "https://app.upfour.io/v1/reports/00000000-0000-4000-8000-000000000001/share" \ -H "Authorization: Bearer $UP4_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "label": "Review with the customer", "never_expires": false }'

const res = await fetch("https://app.upfour.io/v1/reports/00000000-0000-4000-8000-000000000001/share", { method: "POST", headers: { Authorization: `Bearer ${process.env.UP4_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ label: "Review with the customer", never_expires: false, }), }); console.log(res.status, await res.json());

import os import requests res = requests.post( "https://app.upfour.io/v1/reports/00000000-0000-4000-8000-000000000001/share", headers={"Authorization": f"Bearer {os.environ['UP4_API_KEY']}"}, json={ "label": "Review with the customer", "never_expires": False, }, ) print(res.status_code, res.json())

package main import ( "fmt" "io" "net/http" "os" "strings" ) func main() { payload := strings.NewReader(`{ "label": "Review with the customer", "never_expires": false }`) req, _ := http.NewRequest("POST", "https://app.upfour.io/v1/reports/00000000-0000-4000-8000-000000000001/share", payload) req.Header.Set("Authorization", "Bearer "+os.Getenv("UP4_API_KEY")) req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() out, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(out)) }

<?php $payload = <<<'JSON' { "label": "Review with the customer", "never_expires": false } JSON; $ch = curl_init("https://app.upfour.io/v1/reports/00000000-0000-4000-8000-000000000001/share"); curl_setopt_array($ch, [ CURLOPT_CUSTOMREQUEST => "POST", CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("UP4_API_KEY"), "Content-Type: application/json", ], CURLOPT_POSTFIELDS => $payload, ]); $response = curl_exec($ch); echo curl_getinfo($ch, CURLINFO_RESPONSE_CODE), " ", $response, "\n"; curl_close($ch);

{ "data": { "link": { "created_at": "2026-10-27T09:00:00Z", "created_by": "00000000-0000-4000-8000-000000000002", "expires_at": "2027-01-25T09:00:00Z", "format": "pdf", "id": "00000000-0000-4000-8000-000000000003", "label": "Review with the customer", "organization_id": "00000000-0000-4000-8000-000000000004", "range_from": "2026-10-20T09:00:00Z", "range_to": "2026-10-27T09:00:00Z", "report_run_id": "00000000-0000-4000-8000-000000000001", "report_type": "summary", "view_count": 0 }, "token": "••••", "url": "http://example.com:3001/share/reports/••••" } }