Record an operational evidence review

POST

operational-reviews

curl --request POST \
  --url https://api.sempera.org/v1/operational-reviews \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "issue": "<string>",
  "resource": "<string>",
  "evidence_date": "2023-12-25",
  "owner": "<string>",
  "source_sha": "<string>",
  "deployment_sha": "<string>",
  "ci_run": "<string>",
  "evidence_ref": "<string>",
  "acceptance_ref": "<string>"
}
'

import requests

url = "https://api.sempera.org/v1/operational-reviews"

payload = {
    "issue": "<string>",
    "resource": "<string>",
    "evidence_date": "2023-12-25",
    "owner": "<string>",
    "source_sha": "<string>",
    "deployment_sha": "<string>",
    "ci_run": "<string>",
    "evidence_ref": "<string>",
    "acceptance_ref": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    issue: '<string>',
    resource: '<string>',
    evidence_date: '2023-12-25',
    owner: '<string>',
    source_sha: '<string>',
    deployment_sha: '<string>',
    ci_run: '<string>',
    evidence_ref: '<string>',
    acceptance_ref: '<string>'
  })
};

fetch('https://api.sempera.org/v1/operational-reviews', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "issue": "<string>",
  "kind": "provider",
  "resource": "<string>",
  "evidence_date": "2023-12-25",
  "state": "planned",
  "owner": "<string>",
  "next_action": "read-production",
  "blocker": "none",
  "source_sha": "<string>",
  "deployment_sha": "<string>",
  "ci_run": "<string>",
  "evidence_ref": "<string>",
  "acceptance_ref": "<string>",
  "outcome": "pass",
  "reviewed_at": "2023-11-07T05:31:56Z",
  "due_date": "2023-12-25",
  "overdue": true,
  "attestation_only": true,
  "receipt_id": "<string>"
}

{
  "error": {
    "code": "AGENT_ENV_UNPINNED",
    "message": "<string>",
    "request_id": "<string>",
    "field": "<string>",
    "scope": "<string>",
    "reason": "<string>"
  }
}

{
  "error": {
    "code": "AGENT_ENV_UNPINNED",
    "message": "<string>",
    "request_id": "<string>",
    "field": "<string>",
    "scope": "<string>",
    "reason": "<string>"
  }
}

{
  "error": {
    "code": "AGENT_ENV_UNPINNED",
    "message": "<string>",
    "request_id": "<string>",
    "field": "<string>",
    "scope": "<string>",
    "reason": "<string>"
  }
}

{
  "error": {
    "code": "AGENT_ENV_UNPINNED",
    "message": "<string>",
    "request_id": "<string>",
    "field": "<string>",
    "scope": "<string>",
    "reason": "<string>"
  }
}

{
  "error": {
    "code": "AGENT_ENV_UNPINNED",
    "message": "<string>",
    "request_id": "<string>",
    "field": "<string>",
    "scope": "<string>",
    "reason": "<string>"
  }
}

{
  "error": {
    "code": "AGENT_ENV_UNPINNED",
    "message": "<string>",
    "request_id": "<string>",
    "field": "<string>",
    "scope": "<string>",
    "reason": "<string>"
  }
}

{
  "error": {
    "code": "AGENT_ENV_UNPINNED",
    "message": "<string>",
    "request_id": "<string>",
    "field": "<string>",
    "scope": "<string>",
    "reason": "<string>"
  }
}

Authorizations

Authorization

string

header

required

A workspace API key, sent as Authorization: Bearer sempera_sk_... Each operation names the one scope it needs. Scopes, key kinds and roles are in the Authentication guide.

Body

application/json

issue

string

required

Pattern: ^SEM-[1-9][0-9]{0,6}$

kind

enum<string>

required

Available options:

provider,

weekly,

monthly,

credential

resource

string

required

Plain handle, or an existing non-secret credential registry name.

Maximum string length: 80

evidence_date

string<date>

required

Non-future UTC date.

state

enum<string>

required

Available options:

planned,

source-built,

merged,

deployed,

production-verified

owner

string | null

required

Pattern: ^[a-z][a-z0-9-]{1,31}$

next_action

enum<string>

required

Available options:

read-production,

read-provider,

reconcile-linear,

reconcile-cogs,

owner-review,

rotate-credential,

review-scope,

offboard-access,

recovery-drill,

verify-delivery,

review-next-window

blocker

enum<string>

required

Available options:

none,

production-proof,

account-access,

owner-decision,

finance,

legal,

delivery,

acceptance

source_sha

string | null

required

Pattern: ^[0-9a-f]{40}$

deployment_sha

string | null

required

Pattern: ^[0-9a-f]{40}$

ci_run

string | null

required

Pattern: ^[1-9][0-9]{0,19}$

evidence_ref

string | null

required

Maximum string length: 400

acceptance_ref

string

required

Canonical issue URL matching issue. Built states need source_sha and evidence_ref; deployed states also need deployment_sha. Production-verified requires matching SHAs, ci_run and outcome=pass.

Maximum string length: 400

outcome

enum<string>

required

Available options:

pass,

fail,

unknown

Response

Recorded and read back

issue

string

required

Pattern: ^SEM-[1-9][0-9]{0,6}$

kind

enum<string>

required

Available options:

provider,

weekly,

monthly,

credential

resource

string

required

Plain handle, or an existing non-secret credential registry name.

Maximum string length: 80

evidence_date

string<date>

required

Non-future UTC date.

state

enum<string>

required

Available options:

planned,

source-built,

merged,

deployed,

production-verified

owner

string | null

required

Pattern: ^[a-z][a-z0-9-]{1,31}$

next_action

enum<string>

required

Available options:

read-production,

read-provider,

reconcile-linear,

reconcile-cogs,

owner-review,

rotate-credential,

review-scope,

offboard-access,

recovery-drill,

verify-delivery,

review-next-window

blocker

enum<string>

required

Available options:

none,

production-proof,

account-access,

owner-decision,

finance,

legal,

delivery,

acceptance

source_sha

string | null

required

Pattern: ^[0-9a-f]{40}$

deployment_sha

string | null

required

Pattern: ^[0-9a-f]{40}$

ci_run

string | null

required

Pattern: ^[1-9][0-9]{0,19}$

evidence_ref

string | null

required

Maximum string length: 400

acceptance_ref

string

required

Canonical issue URL matching issue. Built states need source_sha and evidence_ref; deployed states also need deployment_sha. Production-verified requires matching SHAs, ci_run and outcome=pass.

Maximum string length: 400

outcome

enum<string>

required

Available options:

pass,

fail,

unknown

reviewed_at

string<date-time>

required

due_date

string<date>

required

overdue

boolean

required

attestation_only

any

required

receipt_id

string

required

⌘I

Record an operational evidence review

curl --request POST \
  --url https://api.sempera.org/v1/operational-reviews \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "issue": "<string>",
  "resource": "<string>",
  "evidence_date": "2023-12-25",
  "owner": "<string>",
  "source_sha": "<string>",
  "deployment_sha": "<string>",
  "ci_run": "<string>",
  "evidence_ref": "<string>",
  "acceptance_ref": "<string>"
}
'

import requests

url = "https://api.sempera.org/v1/operational-reviews"

payload = {
    "issue": "<string>",
    "resource": "<string>",
    "evidence_date": "2023-12-25",
    "owner": "<string>",
    "source_sha": "<string>",
    "deployment_sha": "<string>",
    "ci_run": "<string>",
    "evidence_ref": "<string>",
    "acceptance_ref": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    issue: '<string>',
    resource: '<string>',
    evidence_date: '2023-12-25',
    owner: '<string>',
    source_sha: '<string>',
    deployment_sha: '<string>',
    ci_run: '<string>',
    evidence_ref: '<string>',
    acceptance_ref: '<string>'
  })
};

fetch('https://api.sempera.org/v1/operational-reviews', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "issue": "<string>",
  "kind": "provider",
  "resource": "<string>",
  "evidence_date": "2023-12-25",
  "state": "planned",
  "owner": "<string>",
  "next_action": "read-production",
  "blocker": "none",
  "source_sha": "<string>",
  "deployment_sha": "<string>",
  "ci_run": "<string>",
  "evidence_ref": "<string>",
  "acceptance_ref": "<string>",
  "outcome": "pass",
  "reviewed_at": "2023-11-07T05:31:56Z",
  "due_date": "2023-12-25",
  "overdue": true,
  "attestation_only": true,
  "receipt_id": "<string>"
}

{
  "error": {
    "code": "AGENT_ENV_UNPINNED",
    "message": "<string>",
    "request_id": "<string>",
    "field": "<string>",
    "scope": "<string>",
    "reason": "<string>"
  }
}

{
  "error": {
    "code": "AGENT_ENV_UNPINNED",
    "message": "<string>",
    "request_id": "<string>",
    "field": "<string>",
    "scope": "<string>",
    "reason": "<string>"
  }
}

{
  "error": {
    "code": "AGENT_ENV_UNPINNED",
    "message": "<string>",
    "request_id": "<string>",
    "field": "<string>",
    "scope": "<string>",
    "reason": "<string>"
  }
}

{
  "error": {
    "code": "AGENT_ENV_UNPINNED",
    "message": "<string>",
    "request_id": "<string>",
    "field": "<string>",
    "scope": "<string>",
    "reason": "<string>"
  }
}

{
  "error": {
    "code": "AGENT_ENV_UNPINNED",
    "message": "<string>",
    "request_id": "<string>",
    "field": "<string>",
    "scope": "<string>",
    "reason": "<string>"
  }
}

{
  "error": {
    "code": "AGENT_ENV_UNPINNED",
    "message": "<string>",
    "request_id": "<string>",
    "field": "<string>",
    "scope": "<string>",
    "reason": "<string>"
  }
}

{
  "error": {
    "code": "AGENT_ENV_UNPINNED",
    "message": "<string>",
    "request_id": "<string>",
    "field": "<string>",
    "scope": "<string>",
    "reason": "<string>"
  }
}