Register agent review

Registers a reviewer's judgement of one control against one submission, signed by the reviewer. The review names the submission's evidence for the control, so it judged exactly that. A submission an agent certification was issued for takes no more reviews. Only governance knows who reviews a program, so it registers each review on the reviewer's behalf and vouches for the request with its own token. A member registering reviews directly is refused: otherwise anyone in the organization but the submission's author could write each control's newest review and then certify on them. The body must name submissionCid and evidenceCid, and its outcome is one of satisfied, not_satisfied or not_applicable.

posthttps://<host>/gov/v1/agent/review/{assessment_uuid}

bash

curl --request POST \
  --url 'https://<host>/gov/v1/agent/review/{assessment_uuid}' \
  --header 'Authorization: Bearer <token>' \
  --header 'X-Governance-Authorization: <X-Governance-Authorization>' \
  --header 'Content-Type: application/json' \
  --data '{"attachmentCid":"[\"urn:cid:attachment_cid\"]","controlCid":"urn:cid:control_cid","documentType":"string","evidenceCid":"urn:cid:evidence_cid","extra":{"key":null},"outcome":"satisfied","statement":"The model card covers the agent'\''s tools.","submissionCid":"urn:cid:submission_cid","submittedAt":"2026-10-08T12:00:06Z","submittedBy":"did:key:z6MkvWwG4YJDNEBq6ufypq6mBGpKje7bfJefcQkMoGWPjoq1"}'

javascript

const response = await fetch("https://<host>/gov/v1/agent/review/{assessment_uuid}", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <token>",
    "X-Governance-Authorization": "<X-Governance-Authorization>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "attachmentCid": "[\"urn:cid:attachment_cid\"]",
    "controlCid": "urn:cid:control_cid",
    "documentType": "string",
    "evidenceCid": "urn:cid:evidence_cid",
    "extra": {
      "key": null
    },
    "outcome": "satisfied",
    "statement": "The model card covers the agent's tools.",
    "submissionCid": "urn:cid:submission_cid",
    "submittedAt": "2026-10-08T12:00:06Z",
    "submittedBy": "did:key:z6MkvWwG4YJDNEBq6ufypq6mBGpKje7bfJefcQkMoGWPjoq1"
  })
});

const data = await response.json();

typescript

interface StatementResponse {
  documentCid: string;
  statement: Record<string, unknown>;
  statementCid: string;
}

const response = await fetch("https://<host>/gov/v1/agent/review/{assessment_uuid}", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <token>",
    "X-Governance-Authorization": "<X-Governance-Authorization>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "attachmentCid": "[\"urn:cid:attachment_cid\"]",
    "controlCid": "urn:cid:control_cid",
    "documentType": "string",
    "evidenceCid": "urn:cid:evidence_cid",
    "extra": {
      "key": null
    },
    "outcome": "satisfied",
    "statement": "The model card covers the agent's tools.",
    "submissionCid": "urn:cid:submission_cid",
    "submittedAt": "2026-10-08T12:00:06Z",
    "submittedBy": "did:key:z6MkvWwG4YJDNEBq6ufypq6mBGpKje7bfJefcQkMoGWPjoq1"
  })
});
if (!response.ok) throw new Error(`${response.status} ${response.statusText}`);

const data: StatementResponse = await response.json();

python

import requests

response = requests.post(
    "https://<host>/gov/v1/agent/review/{assessment_uuid}",
    headers={
        "Authorization": "Bearer <token>",
        "X-Governance-Authorization": "<X-Governance-Authorization>",
        "Content-Type": "application/json",
    },
    json={
        "attachmentCid": "[\"urn:cid:attachment_cid\"]",
        "controlCid": "urn:cid:control_cid",
        "documentType": "string",
        "evidenceCid": "urn:cid:evidence_cid",
        "extra": {
            "key": None,
        },
        "outcome": "satisfied",
        "statement": "The model card covers the agent's tools.",
        "submissionCid": "urn:cid:submission_cid",
        "submittedAt": "2026-10-08T12:00:06Z",
        "submittedBy": "did:key:z6MkvWwG4YJDNEBq6ufypq6mBGpKje7bfJefcQkMoGWPjoq1",
    },
)
response.raise_for_status()
print(response.json())

package main

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

func main() {
	body := strings.NewReader(`{
	  "attachmentCid": "[\"urn:cid:attachment_cid\"]",
	  "controlCid": "urn:cid:control_cid",
	  "documentType": "string",
	  "evidenceCid": "urn:cid:evidence_cid",
	  "extra": {
	    "key": null
	  },
	  "outcome": "satisfied",
	  "statement": "The model card covers the agent's tools.",
	  "submissionCid": "urn:cid:submission_cid",
	  "submittedAt": "2026-10-08T12:00:06Z",
	  "submittedBy": "did:key:z6MkvWwG4YJDNEBq6ufypq6mBGpKje7bfJefcQkMoGWPjoq1"
	}`)
	req, err := http.NewRequest(http.MethodPost, "https://<host>/gov/v1/agent/review/{assessment_uuid}", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer <token>")
	req.Header.Set("X-Governance-Authorization", "<X-Governance-Authorization>")
	req.Header.Set("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	data, err := io.ReadAll(res.Body)
	if err != nil {
		panic(err)
	}
	fmt.Println(res.Status, string(data))
}

java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Example {
    public static void main(String[] args) throws Exception {
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://<host>/gov/v1/agent/review/{assessment_uuid}"))
            .header("Authorization", "Bearer <token>")
            .header("X-Governance-Authorization", "<X-Governance-Authorization>")
            .header("Content-Type", "application/json")
            .method("POST", HttpRequest.BodyPublishers.ofString("""
                {
                  "attachmentCid": "[\\"urn:cid:attachment_cid\\"]",
                  "controlCid": "urn:cid:control_cid",
                  "documentType": "string",
                  "evidenceCid": "urn:cid:evidence_cid",
                  "extra": {
                    "key": null
                  },
                  "outcome": "satisfied",
                  "statement": "The model card covers the agent's tools.",
                  "submissionCid": "urn:cid:submission_cid",
                  "submittedAt": "2026-10-08T12:00:06Z",
                  "submittedBy": "did:key:z6MkvWwG4YJDNEBq6ufypq6mBGpKje7bfJefcQkMoGWPjoq1"
                }
                """))
            .build();

        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.statusCode() + " " + response.body());
    }
}

csharp

using System.Net.Http.Headers;
using System.Text;

using var client = new HttpClient();
using var request = new HttpRequestMessage(HttpMethod.Post, "https://<host>/gov/v1/agent/review/{assessment_uuid}");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", "<token>");
request.Headers.Add("X-Governance-Authorization", "<X-Governance-Authorization>");
request.Content = new StringContent("""
    {
      "attachmentCid": "[\"urn:cid:attachment_cid\"]",
      "controlCid": "urn:cid:control_cid",
      "documentType": "string",
      "evidenceCid": "urn:cid:evidence_cid",
      "extra": {
        "key": null
      },
      "outcome": "satisfied",
      "statement": "The model card covers the agent's tools.",
      "submissionCid": "urn:cid:submission_cid",
      "submittedAt": "2026-10-08T12:00:06Z",
      "submittedBy": "did:key:z6MkvWwG4YJDNEBq6ufypq6mBGpKje7bfJefcQkMoGWPjoq1"
    }
    """, Encoding.UTF8, "application/json");

using var response = await client.SendAsync(request);
Console.WriteLine($"{(int)response.StatusCode} {await response.Content.ReadAsStringAsync()}");

php

<?php

$ch = curl_init('https://<host>/gov/v1/agent/review/{assessment_uuid}');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer <token>',
        'X-Governance-Authorization: <X-Governance-Authorization>',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => <<<'JSON'
    {
      "attachmentCid": "[\"urn:cid:attachment_cid\"]",
      "controlCid": "urn:cid:control_cid",
      "documentType": "string",
      "evidenceCid": "urn:cid:evidence_cid",
      "extra": {
        "key": null
      },
      "outcome": "satisfied",
      "statement": "The model card covers the agent's tools.",
      "submissionCid": "urn:cid:submission_cid",
      "submittedAt": "2026-10-08T12:00:06Z",
      "submittedBy": "did:key:z6MkvWwG4YJDNEBq6ufypq6mBGpKje7bfJefcQkMoGWPjoq1"
    }
    JSON,
    CURLOPT_RETURNTRANSFER => true,
]);

$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
echo $status . " " . $response . PHP_EOL;

ruby

require "net/http"

uri = URI("https://<host>/gov/v1/agent/review/{assessment_uuid}")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer <token>"
request["X-Governance-Authorization"] = "<X-Governance-Authorization>"
request["Content-Type"] = "application/json"
request.body = <<~'JSON'
  {
    "attachmentCid": "[\"urn:cid:attachment_cid\"]",
    "controlCid": "urn:cid:control_cid",
    "documentType": "string",
    "evidenceCid": "urn:cid:evidence_cid",
    "extra": {
      "key": null
    },
    "outcome": "satisfied",
    "statement": "The model card covers the agent's tools.",
    "submissionCid": "urn:cid:submission_cid",
    "submittedAt": "2026-10-08T12:00:06Z",
    "submittedBy": "did:key:z6MkvWwG4YJDNEBq6ufypq6mBGpKje7bfJefcQkMoGWPjoq1"
  }
JSON

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http|
  http.request(request)
end
puts "#{response.code} #{response.body}"

rust

// Cargo.toml dependencies: reqwest (features "json"), serde_json, tokio (features "full")
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let response = reqwest::Client::new()
        .post("https://<host>/gov/v1/agent/review/{assessment_uuid}")
        .header("Authorization", "Bearer <token>")
        .header("X-Governance-Authorization", "<X-Governance-Authorization>")
        .json(&json!({
            "attachmentCid": "[\"urn:cid:attachment_cid\"]",
            "controlCid": "urn:cid:control_cid",
            "documentType": "string",
            "evidenceCid": "urn:cid:evidence_cid",
            "extra": {
                "key": null
            },
            "outcome": "satisfied",
            "statement": "The model card covers the agent's tools.",
            "submissionCid": "urn:cid:submission_cid",
            "submittedAt": "2026-10-08T12:00:06Z",
            "submittedBy": "did:key:z6MkvWwG4YJDNEBq6ufypq6mBGpKje7bfJefcQkMoGWPjoq1"
        }))
        .send()
        .await?;

    println!("{} {}", response.status(), response.text().await?);
    Ok(())
}

Authorizations

BearerAuth · HTTP bearer (JWT)

Parameters

Path parameters

Name	Type	Description
`assessment_uuid` required	`string<uuid>`	The assessment graph

Header parameters

Name	Type	Description
`X-Governance-Authorization` required	`string`	Governance's own bearer token, `Bearer <token>`, which it adds when it forwards a review, having checked the reviewer reviews the program

Request bodyrequired

application/json

attachmentCidstring[]
controlCidstringrequired
The program control judged
documentTypestring
evidenceCidstringrequired
The evidence the reviewer weighed: the submission's evidence for the control, which names the declarations covering it, its not-applicable claim and the configuration fields and profile sections it judges
extraobject | null
Show properties
Map of any
outcomeControlOutcomerequired
A reviewer's finding on one control
One ofsatisfiednot_satisfiednot_applicable
statementstring | null
submissionCidstringrequired
The submission judged
submittedAtstring<date-time>required
submittedBystringrequired

Examplejson

{
  "attachmentCid": "[\"urn:cid:attachment_cid\"]",
  "controlCid": "urn:cid:control_cid",
  "documentType": "string",
  "evidenceCid": "urn:cid:evidence_cid",
  "extra": {
    "key": null
  },
  "outcome": "satisfied",
  "statement": "The model card covers the agent's tools.",
  "submissionCid": "urn:cid:submission_cid",
  "submittedAt": "2026-10-08T12:00:06Z",
  "submittedBy": "did:key:z6MkvWwG4YJDNEBq6ufypq6mBGpKje7bfJefcQkMoGWPjoq1"
}

Responses

200Governance statement created for the review

application/json

documentCidstringrequired
statementGovernanceStatementrequired
Records governance information for a subject This statement type associates governance documents (policies, procedures, compliance documents) with subjects in the lineage system.
Show GovernanceStatement
- @contextstringrequired
  JSON-LD context URL
- @idstringrequired
  Unique identifier for this statement
- @typestringrequired
  Statement type identifier
- documentstringrequired
  CID of the governance document
- registeredBystringrequired
  DID of the entity that registered this statement
- subjectstringrequired
  The subject to which governance applies
- timestampstringrequired
  ISO 8601 timestamp of when the statement was created
statementCidstringrequired

Examplejson

{
  "documentCid": "string",
  "statement": {
    "@context": "string",
    "@id": "string",
    "@type": "string",
    "document": "string",
    "registeredBy": "string",
    "subject": "string",
    "timestamp": "string"
  },
  "statementCid": "string"
}

401Missing or invalid bearer or X-Governance-Authorization token, or submittedBy is not the caller's DID

application/json

callstackobject
Show properties
object | null
errorstringrequired

Examplejson

{
  "callstack": {},
  "error": "string"
}

403The request carries no X-Governance-Authorization header whose token holds organization-level certify_agents, or the assessment graph is not registered, or belongs to an organization other than the caller's

application/json

callstackobject
Show properties
object | null
errorstringrequired

Examplejson

{
  "callstack": {},
  "error": "string"
}

409The same review document is already registered (vary its submittedAt), or the submission is certified, which closes it to review

application/json

callstackobject
Show properties
object | null
errorstringrequired

Examplejson

{
  "callstack": {},
  "error": "string"
}

422The review is not a review, judges a control outside the program, cites a submission not registered in the assessment, or names evidence other than the submission's for the control; or the submission was registered before controls named their evidence

application/json

callstackobject
Show properties
object | null
errorstringrequired

Examplejson

{
  "callstack": {},
  "error": "string"
}

500Internal error

application/json

callstackobject
Show properties
object | null
errorstringrequired

Examplejson

{
  "callstack": {},
  "error": "string"
}

503Auth Service or blob storage unavailable

application/json

callstackobject
Show properties
object | null
errorstringrequired

Examplejson

{
  "callstack": {},
  "error": "string"
}