Create Governance Program

Create one immutable version of a Governance Program, independent of the policy library, and register its manifest with the Integrity Service. A new version is a new program with the same name and a version higher than every existing one, by SemVer precedence. Rejected when the program could certify an agent without judging it: no controls, every control waivable as not applicable, or a scope requiring no configuration field. A control states its requirement, may list the evidence it expects an owner to declare and the sources it cites, names the operating profile sections and configuration fields it is judged against (each configuration field one the scope requires), and may say which agents it applies to by their operating profile. Requires organization-level manage_programs

posthttps://localhost:10001/api/v1/organizations/{orgId}/programs

bash

curl --request POST \
  --url 'https://localhost:10001/api/v1/organizations/{orgId}/programs' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{"certification":{"validFor":"P1Y"},"controls":[{"appliesWhen":{"any":[{"field":"context.mode","in":["personal"]}]},"citations":[{"title":"string","url":"string"}],"controlCode":"AGT-1","expectedEvidence":["The model card for the agent'\''s model"],"guidance":"string","judges":{"configuration":["app"],"profile":["purpose"]},"notApplicable":{"condition":"string","permitted":true},"requirement":"string","title":"string"}],"description":"string","name":"Agent Baseline","scope":{"requiredCoverage":["app"]},"version":"1.0.0"}'

javascript

const response = await fetch("https://localhost:10001/api/v1/organizations/{orgId}/programs", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "certification": {
      "validFor": "P1Y"
    },
    "controls": [
      {
        "appliesWhen": {
          "any": [
            {
              "field": "context.mode",
              "in": [
                "personal"
              ]
            }
          ]
        },
        "citations": [
          {
            "title": "string",
            "url": "string"
          }
        ],
        "controlCode": "AGT-1",
        "expectedEvidence": [
          "The model card for the agent's model"
        ],
        "guidance": "string",
        "judges": {
          "configuration": [
            "app"
          ],
          "profile": [
            "purpose"
          ]
        },
        "notApplicable": {
          "condition": "string",
          "permitted": true
        },
        "requirement": "string",
        "title": "string"
      }
    ],
    "description": "string",
    "name": "Agent Baseline",
    "scope": {
      "requiredCoverage": [
        "app"
      ]
    },
    "version": "1.0.0"
  })
});

const data = await response.json();

typescript

interface Program {
  certification?: Record<string, unknown>;
  controls?: Record<string, unknown>[];
  createdAt?: string;
  createdBy?: string;
  createdByDid?: string;
  createdByUserId?: string;
  description?: string;
  manifestCid?: string;
  name?: string;
  organizationId?: number;
  organizationUuid?: string;
  scope?: Record<string, unknown>;
  slug?: string;
  uuid?: string;
  version?: string;
}

const response = await fetch("https://localhost:10001/api/v1/organizations/{orgId}/programs", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "certification": {
      "validFor": "P1Y"
    },
    "controls": [
      {
        "appliesWhen": {
          "any": [
            {
              "field": "context.mode",
              "in": [
                "personal"
              ]
            }
          ]
        },
        "citations": [
          {
            "title": "string",
            "url": "string"
          }
        ],
        "controlCode": "AGT-1",
        "expectedEvidence": [
          "The model card for the agent's model"
        ],
        "guidance": "string",
        "judges": {
          "configuration": [
            "app"
          ],
          "profile": [
            "purpose"
          ]
        },
        "notApplicable": {
          "condition": "string",
          "permitted": true
        },
        "requirement": "string",
        "title": "string"
      }
    ],
    "description": "string",
    "name": "Agent Baseline",
    "scope": {
      "requiredCoverage": [
        "app"
      ]
    },
    "version": "1.0.0"
  })
});
if (!response.ok) throw new Error(`${response.status} ${response.statusText}`);

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

python

import requests

response = requests.post(
    "https://localhost:10001/api/v1/organizations/{orgId}/programs",
    headers={
        "Authorization": "Bearer <token>",
        "Content-Type": "application/json",
    },
    json={
        "certification": {
            "validFor": "P1Y",
        },
        "controls": [
            {
                "appliesWhen": {
                    "any": [
                        {
                            "field": "context.mode",
                            "in": [
                                "personal",
                            ],
                        },
                    ],
                },
                "citations": [
                    {
                        "title": "string",
                        "url": "string",
                    },
                ],
                "controlCode": "AGT-1",
                "expectedEvidence": [
                    "The model card for the agent's model",
                ],
                "guidance": "string",
                "judges": {
                    "configuration": [
                        "app",
                    ],
                    "profile": [
                        "purpose",
                    ],
                },
                "notApplicable": {
                    "condition": "string",
                    "permitted": True,
                },
                "requirement": "string",
                "title": "string",
            },
        ],
        "description": "string",
        "name": "Agent Baseline",
        "scope": {
            "requiredCoverage": [
                "app",
            ],
        },
        "version": "1.0.0",
    },
)
response.raise_for_status()
print(response.json())

package main

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

func main() {
	body := strings.NewReader(`{
	  "certification": {
	    "validFor": "P1Y"
	  },
	  "controls": [
	    {
	      "appliesWhen": {
	        "any": [
	          {
	            "field": "context.mode",
	            "in": [
	              "personal"
	            ]
	          }
	        ]
	      },
	      "citations": [
	        {
	          "title": "string",
	          "url": "string"
	        }
	      ],
	      "controlCode": "AGT-1",
	      "expectedEvidence": [
	        "The model card for the agent's model"
	      ],
	      "guidance": "string",
	      "judges": {
	        "configuration": [
	          "app"
	        ],
	        "profile": [
	          "purpose"
	        ]
	      },
	      "notApplicable": {
	        "condition": "string",
	        "permitted": true
	      },
	      "requirement": "string",
	      "title": "string"
	    }
	  ],
	  "description": "string",
	  "name": "Agent Baseline",
	  "scope": {
	    "requiredCoverage": [
	      "app"
	    ]
	  },
	  "version": "1.0.0"
	}`)
	req, err := http.NewRequest(http.MethodPost, "https://localhost:10001/api/v1/organizations/{orgId}/programs", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer <token>")
	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://localhost:10001/api/v1/organizations/{orgId}/programs"))
            .header("Authorization", "Bearer <token>")
            .header("Content-Type", "application/json")
            .method("POST", HttpRequest.BodyPublishers.ofString("""
                {
                  "certification": {
                    "validFor": "P1Y"
                  },
                  "controls": [
                    {
                      "appliesWhen": {
                        "any": [
                          {
                            "field": "context.mode",
                            "in": [
                              "personal"
                            ]
                          }
                        ]
                      },
                      "citations": [
                        {
                          "title": "string",
                          "url": "string"
                        }
                      ],
                      "controlCode": "AGT-1",
                      "expectedEvidence": [
                        "The model card for the agent's model"
                      ],
                      "guidance": "string",
                      "judges": {
                        "configuration": [
                          "app"
                        ],
                        "profile": [
                          "purpose"
                        ]
                      },
                      "notApplicable": {
                        "condition": "string",
                        "permitted": true
                      },
                      "requirement": "string",
                      "title": "string"
                    }
                  ],
                  "description": "string",
                  "name": "Agent Baseline",
                  "scope": {
                    "requiredCoverage": [
                      "app"
                    ]
                  },
                  "version": "1.0.0"
                }
                """))
            .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://localhost:10001/api/v1/organizations/{orgId}/programs");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", "<token>");
request.Content = new StringContent("""
    {
      "certification": {
        "validFor": "P1Y"
      },
      "controls": [
        {
          "appliesWhen": {
            "any": [
              {
                "field": "context.mode",
                "in": [
                  "personal"
                ]
              }
            ]
          },
          "citations": [
            {
              "title": "string",
              "url": "string"
            }
          ],
          "controlCode": "AGT-1",
          "expectedEvidence": [
            "The model card for the agent's model"
          ],
          "guidance": "string",
          "judges": {
            "configuration": [
              "app"
            ],
            "profile": [
              "purpose"
            ]
          },
          "notApplicable": {
            "condition": "string",
            "permitted": true
          },
          "requirement": "string",
          "title": "string"
        }
      ],
      "description": "string",
      "name": "Agent Baseline",
      "scope": {
        "requiredCoverage": [
          "app"
        ]
      },
      "version": "1.0.0"
    }
    """, 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://localhost:10001/api/v1/organizations/{orgId}/programs');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer <token>',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => <<<'JSON'
    {
      "certification": {
        "validFor": "P1Y"
      },
      "controls": [
        {
          "appliesWhen": {
            "any": [
              {
                "field": "context.mode",
                "in": [
                  "personal"
                ]
              }
            ]
          },
          "citations": [
            {
              "title": "string",
              "url": "string"
            }
          ],
          "controlCode": "AGT-1",
          "expectedEvidence": [
            "The model card for the agent's model"
          ],
          "guidance": "string",
          "judges": {
            "configuration": [
              "app"
            ],
            "profile": [
              "purpose"
            ]
          },
          "notApplicable": {
            "condition": "string",
            "permitted": true
          },
          "requirement": "string",
          "title": "string"
        }
      ],
      "description": "string",
      "name": "Agent Baseline",
      "scope": {
        "requiredCoverage": [
          "app"
        ]
      },
      "version": "1.0.0"
    }
    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://localhost:10001/api/v1/organizations/{orgId}/programs")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer <token>"
request["Content-Type"] = "application/json"
request.body = <<~'JSON'
  {
    "certification": {
      "validFor": "P1Y"
    },
    "controls": [
      {
        "appliesWhen": {
          "any": [
            {
              "field": "context.mode",
              "in": [
                "personal"
              ]
            }
          ]
        },
        "citations": [
          {
            "title": "string",
            "url": "string"
          }
        ],
        "controlCode": "AGT-1",
        "expectedEvidence": [
          "The model card for the agent's model"
        ],
        "guidance": "string",
        "judges": {
          "configuration": [
            "app"
          ],
          "profile": [
            "purpose"
          ]
        },
        "notApplicable": {
          "condition": "string",
          "permitted": true
        },
        "requirement": "string",
        "title": "string"
      }
    ],
    "description": "string",
    "name": "Agent Baseline",
    "scope": {
      "requiredCoverage": [
        "app"
      ]
    },
    "version": "1.0.0"
  }
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://localhost:10001/api/v1/organizations/{orgId}/programs")
        .header("Authorization", "Bearer <token>")
        .json(&json!({
            "certification": {
                "validFor": "P1Y"
            },
            "controls": [
                {
                    "appliesWhen": {
                        "any": [
                            {
                                "field": "context.mode",
                                "in": [
                                    "personal"
                                ]
                            }
                        ]
                    },
                    "citations": [
                        {
                            "title": "string",
                            "url": "string"
                        }
                    ],
                    "controlCode": "AGT-1",
                    "expectedEvidence": [
                        "The model card for the agent's model"
                    ],
                    "guidance": "string",
                    "judges": {
                        "configuration": [
                            "app"
                        ],
                        "profile": [
                            "purpose"
                        ]
                    },
                    "notApplicable": {
                        "condition": "string",
                        "permitted": true
                    },
                    "requirement": "string",
                    "title": "string"
                }
            ],
            "description": "string",
            "name": "Agent Baseline",
            "scope": {
                "requiredCoverage": [
                    "app"
                ]
            },
            "version": "1.0.0"
        }))
        .send()
        .await?;

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

Authorizations

BearerAuth · API key in header "Authorization" — Type "Bearer" followed by a space and JWT token.

Parameters

Path parameters

Name	Type	Description
`orgId` required	`string`	Organization ID or UUID (urn:uuid optional)

Request bodyrequired

Program and its controls

application/json

certificationhandlers.ProgramCertificationRequest
Show handlers.ProgramCertificationRequest
- validForstring
  ISO 8601 duration in years, months, weeks, or days; omit for no expiry
controlshandlers.ProgramControlRequest[]required
At least one control is required
Show properties
Array of handlers.ProgramControlRequest
- appliesWhenobject
  Which agents the control applies to, by their operating profile; omit for every agent
  Show properties
  anycore.ApplicabilityCondition[]
  At least one, each field once; stored and frozen sorted by field
  Show properties
  Array of core.ApplicabilityCondition
  fieldobject
  One ofcontext.modecontext.actsForcontext.userssystems.accesssystems.datasystems.operations.impact
  Show properties
  object (enum) · one of context.mode, context.actsFor, context.users, systems.access, systems.data, systems.operations.impact
  instring[]
  At least one, each once, each a value the field can hold; stored and frozen sorted
- citationscore.Citation[]
  The standards or frameworks the control derives from; at most 20
  Show properties
  Array of core.Citation
  titlestring
  Up to 255 characters; trimmed
  urlstring
  An absolute http or https URL with a hostname, up to 2048 bytes; trimmed
- controlCodestringrequired
  Alphanumeric, . and -; upper-cased
- expectedEvidencestring[]
  What the owner is expected to declare, as guidance; at most 20
- guidancestring
- judgesobject
  Operating profile sections and configuration fields the control is judged against; each configuration field must be one the scope requires
  Show properties
  configurationcore.ConfigurationField[]
  Each once, each one the scope requires; stored and frozen sorted
  profilecore.ProfileSection[]
  Each once; stored and frozen sorted
- notApplicablecore.NotApplicableRule
  Show core.NotApplicableRule
  conditionstring
  Required when permitted, rejected otherwise
  permittedboolean
- requirementstringrequired
- titlestringrequired
descriptionstringrequired
namestringrequired
scopehandlers.ProgramScopeRequestrequired
Show handlers.ProgramScopeRequest
- requiredCoveragecore.ConfigurationField[]required
  AgentConfigurationV1 fields an assessed agent's snapshot must have captured; at least one
versionstringrequired
SemVer with no leading "v" or build metadata

Examplejson

{
  "certification": {
    "validFor": "P1Y"
  },
  "controls": [
    {
      "appliesWhen": {
        "any": [
          {
            "field": "context.mode",
            "in": [
              "personal"
            ]
          }
        ]
      },
      "citations": [
        {
          "title": "string",
          "url": "string"
        }
      ],
      "controlCode": "AGT-1",
      "expectedEvidence": [
        "The model card for the agent's model"
      ],
      "guidance": "string",
      "judges": {
        "configuration": [
          "app"
        ],
        "profile": [
          "purpose"
        ]
      },
      "notApplicable": {
        "condition": "string",
        "permitted": true
      },
      "requirement": "string",
      "title": "string"
    }
  ],
  "description": "string",
  "name": "Agent Baseline",
  "scope": {
    "requiredCoverage": [
      "app"
    ]
  },
  "version": "1.0.0"
}

Responses

201Created program, with its controls and manifest CID

application/json

certificationcore.ProgramCertification
The rule an assessment must meet to certify under this program, and how long the certification lasts
Show core.ProgramCertification
- ruleobjectread-only
  One ofall_controls_satisfied
  Show properties
  object (enum) · one of all_controls_satisfied
- validForstring
  ISO 8601 duration in years, months, weeks, or days; absent when the program sets no expiry
controlscore.ProgramControl[]
Show properties
Array of core.ProgramControl
- appliesWhenobject
  Absent when the control applies to every agent
  Show properties
  anycore.ApplicabilityCondition[]
  At least one, each field once; stored and frozen sorted by field
  Show properties
  Array of core.ApplicabilityCondition
  fieldobject
  One ofcontext.modecontext.actsForcontext.userssystems.accesssystems.datasystems.operations.impact
  Show properties
  object (enum) · one of context.mode, context.actsFor, context.users, systems.access, systems.data, systems.operations.impact
  instring[]
  At least one, each once, each a value the field can hold; stored and frozen sorted
- citationscore.Citation[]
  The standards or frameworks the control derives from, as a policy control cites them
  Show properties
  Array of core.Citation
  titlestring
  Up to 255 characters; trimmed
  urlstring
  An absolute http or https URL with a hostname, up to 2048 bytes; trimmed
- controlCodestring
  Alphanumeric, . and -; upper-cased; unique within the program
- createdAtstring<date-time>read-only
- expectedEvidencestring[]
  What the owner is expected to declare, as guidance for them and the reviewer; nothing checks it
- guidancestring
- judgescore.ProgramJudges
  Show core.ProgramJudges
  configurationcore.ConfigurationField[]
  Each once, each one the scope requires; stored and frozen sorted
  profilecore.ProfileSection[]
  Each once; stored and frozen sorted
- notApplicablecore.NotApplicableRule
  Show core.NotApplicableRule
  conditionstring
  Required when permitted, rejected otherwise
  permittedboolean
- requirementstring
- titlestring
- uuidstringread-only
  urn:uuid form
createdAtstring<date-time>read-only
createdBystringread-only
createdByDidstringread-only
Verifiable actor; createdBy is the label
createdByUserIdstringread-only
The creator's user ID; absent on versions created before it was recorded
descriptionstring
manifestCidstringread-only
Assigned by the Integrity Service at creation
namestring
organizationIdintegerread-only
Taken from the path on create
organizationUuidstringread-only
urn:uuid form; the owner named in the manifest
scopecore.ProgramScope
The agent configuration a certification under this program binds: the configuration schema, and the fields an assessed agent's snapshot must have captured
Show core.ProgramScope
- configurationstringread-only
  The schema the fields belong to; always AgentConfigurationV1 today
- requiredCoveragecore.ConfigurationField[]
  At least one, each once; stored and frozen sorted
slugstringread-only
Derived from name; shared by every version of the program
uuidstringread-only
urn:uuid form
versionstring
SemVer with no leading "v" or build metadata, e.g. 1.2.3

Examplejson

{
  "certification": {
    "validFor": "P1Y"
  },
  "controls": [
    {
      "appliesWhen": {
        "any": [
          {
            "field": "context.mode",
            "in": [
              "personal"
            ]
          }
        ]
      },
      "citations": [
        {
          "title": "string",
          "url": "string"
        }
      ],
      "controlCode": "string",
      "expectedEvidence": [
        "string"
      ],
      "guidance": "string",
      "judges": {
        "configuration": [
          "app"
        ],
        "profile": [
          "purpose"
        ]
      },
      "notApplicable": {
        "condition": "string",
        "permitted": true
      },
      "requirement": "string",
      "title": "string"
    }
  ],
  "createdAt": "2025-01-01T00:00:00Z",
  "createdBy": "string",
  "createdByDid": "string",
  "createdByUserId": "string",
  "description": "string",
  "manifestCid": "string",
  "name": "string",
  "organizationId": 0,
  "organizationUuid": "string",
  "scope": {
    "requiredCoverage": [
      "app"
    ]
  },
  "slug": "string",
  "uuid": "string",
  "version": "string"
}

400Bad request - Invalid organization ID, request body, or requirements, the name and version are already taken in this organization, or the version is not higher than the program's latest

application/json

errorstring

Examplejson

{
  "error": "Invalid request body"
}

401Unauthorized - Authentication required

application/json

errorstring

Examplejson

{
  "error": "Invalid request body"
}

403Forbidden - No organization access or insufficient permissions

application/json

errorstring

Examplejson

{
  "error": "Invalid request body"
}

404Organization not found

application/json

errorstring

Examplejson

{
  "error": "Invalid request body"
}

409Conflict - Lost to a concurrent create of the same name and version

application/json

errorstring

Examplejson

{
  "error": "Invalid request body"
}

500Internal server error

application/json

errorstring

Examplejson

{
  "error": "Invalid request body"
}