Download a submitted version's archived document

curl --request GET \
  --url https://api.ctrl-hub.com/v3/form-submission-versions/{version_id}/artefact \
  --header 'X-Session-Token: <api-key>'

import requests

url = "https://api.ctrl-hub.com/v3/form-submission-versions/{version_id}/artefact"

headers = {"X-Session-Token": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {'X-Session-Token': '<api-key>'}};

fetch('https://api.ctrl-hub.com/v3/form-submission-versions/{version_id}/artefact', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.ctrl-hub.com/v3/form-submission-versions/{version_id}/artefact",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-Session-Token: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.ctrl-hub.com/v3/form-submission-versions/{version_id}/artefact"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-Session-Token", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.ctrl-hub.com/v3/form-submission-versions/{version_id}/artefact")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-Session-Token"] = '<api-key>'

response = http.request(request)
puts response.read_body

"<string>"

{
  "id": "98ca4a78-b66f-4234-9719-aaf832ee6669",
  "status": "400",
  "title": "A validation error was encountered",
  "source": {
    "parameter": "include"
  },
  "meta": {
    "resource": "wrong_value"
  }
}

{
  "id": "05fc9c8d-73b9-4697-9337-57f7a567a48f",
  "status": "401",
  "title": "You are not authorised to access this resource",
  "detail": "In order to access this resource, you need the 'admin' role.",
  "code": "AUTH.001"
}

{
  "id": "7b4c8f12-3e9a-4d5b-8c6f-1a2b3c4d5e6f",
  "status": "404",
  "title": "Resource not found",
  "detail": "The requested resource could not be found or does not exist.",
  "code": "NOT_FOUND.001"
}

{
  "id": "8e2f9a34-b5c6-4d7e-9f8a-2b3c4d5e6f7g",
  "status": "409",
  "title": "Conflict",
  "detail": "The request conflicts with the current state of the resource.",
  "code": "CONFLICT.001"
}

{
  "id": "fe9d9a69-f0a7-4fdc-bb2c-176027f316c5",
  "status": "500",
  "title": "Internal Server Error",
  "detail": "An unexpected error occurred on the server."
}

Submissions

Download a submitted version's archived document

Stream the archived PDF of a submitted version.

There are no signed download URLs anywhere in this platform, so this is how the document is fetched: the request is authenticated and authorised like any other and the bytes are streamed through it. Authorisation is therefore checked when the file is fetched rather than when a link was minted, so a grant withdrawn after the document was generated stops the download.

Authorised exactly as reading the version is. The document contains what the version contains, so anybody who may read one may read the other, and there is no separate permission to hold.

Each fetch is recorded in the audit trail. Retention answers what was issued; the audit record answers who took it.

A version whose document is still generating, or whose generation failed, returns a conflict rather than an empty file. A version that never had one, which is anything submitted before archiving was switched on, returns a not found.

Served by a custom handler rather than a generated one, because it returns a file rather than a JSON:API document.

GET

form-submission-versions

{version_id}

artefact

Download a submitted version's archived document

curl --request GET \
  --url https://api.ctrl-hub.com/v3/form-submission-versions/{version_id}/artefact \
  --header 'X-Session-Token: <api-key>'

import requests

url = "https://api.ctrl-hub.com/v3/form-submission-versions/{version_id}/artefact"

headers = {"X-Session-Token": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {'X-Session-Token': '<api-key>'}};

fetch('https://api.ctrl-hub.com/v3/form-submission-versions/{version_id}/artefact', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.ctrl-hub.com/v3/form-submission-versions/{version_id}/artefact",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-Session-Token: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.ctrl-hub.com/v3/form-submission-versions/{version_id}/artefact"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-Session-Token", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.ctrl-hub.com/v3/form-submission-versions/{version_id}/artefact")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-Session-Token"] = '<api-key>'

response = http.request(request)
puts response.read_body

"<string>"

{
  "id": "98ca4a78-b66f-4234-9719-aaf832ee6669",
  "status": "400",
  "title": "A validation error was encountered",
  "source": {
    "parameter": "include"
  },
  "meta": {
    "resource": "wrong_value"
  }
}

{
  "id": "05fc9c8d-73b9-4697-9337-57f7a567a48f",
  "status": "401",
  "title": "You are not authorised to access this resource",
  "detail": "In order to access this resource, you need the 'admin' role.",
  "code": "AUTH.001"
}

{
  "id": "7b4c8f12-3e9a-4d5b-8c6f-1a2b3c4d5e6f",
  "status": "404",
  "title": "Resource not found",
  "detail": "The requested resource could not be found or does not exist.",
  "code": "NOT_FOUND.001"
}

{
  "id": "8e2f9a34-b5c6-4d7e-9f8a-2b3c4d5e6f7g",
  "status": "409",
  "title": "Conflict",
  "detail": "The request conflicts with the current state of the resource.",
  "code": "CONFLICT.001"
}

{
  "id": "fe9d9a69-f0a7-4fdc-bb2c-176027f316c5",
  "status": "500",
  "title": "Internal Server Error",
  "detail": "An unexpected error occurred on the server."
}

Authorizations

X-Session-Token

string

header

required

Session token for authentication.

Path Parameters

version_id

string<uuid>

required

The unique identifier for the version.

Response

The archived document.

The response is of type file.