Skip to main content
POST
/
v1
/
witness
Create Witness Group
curl --request POST \
  --url https://api.truthlocks.com/v1/witness \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "name": "Model Validation Panel",
  "required_attestations": 3,
  "agent_ids": [
    "550e8400-e29b-41d4-a716-446655440000",
    "550e8400-e29b-41d4-a716-446655440001",
    "550e8400-e29b-41d4-a716-446655440002",
    "550e8400-e29b-41d4-a716-446655440003"
  ]
}
'
{
  "witness_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "name": "<string>",
  "required_attestations": 123,
  "agent_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "status": "pending",
  "created_at": "2023-11-07T05:31:56Z"
}
Creates a new witness request that coordinates multiple independent machine agents to verify a truth claim. Witness verification is a core primitive of the MAIP protocol — it provides Byzantine-fault-tolerant consensus by requiring a quorum of trusted agents to independently attest to a claim before it is accepted. The system selects eligible witnesses based on their trust scores, excluding the originating agent and any agents below the minimum trust threshold. If explicit witness_agent_ids are provided, those agents are invited directly (subject to trust score validation).

​
Authentication

Requires X-API-Key header or Bearer JWT token. Tenant-scoped via X-Tenant-ID.

​
Request Body

​
claim_id
string
required
The identifier of the truth claim to be witnessed. Must reference an existing claim in pending or verifying status. Format: maip-tc:ULID.
​
required_witnesses
integer
default:"3"
The number of witness attestations required to reach consensus. Minimum: 1. Maximum: 10. Higher values increase verification confidence but take longer.
​
witness_agent_ids
string[]
Optional list of specific agent identifiers to invite as witnesses. If omitted, the system auto-selects eligible agents from the tenant’s agent pool. Format: maip-agent:ULID.
​
min_trust_score
number
default:"0.5"
Minimum trust score required for an agent to participate as a witness. Range: 0.0-1.0. Agents below this threshold are excluded from selection.
​
ttl_seconds
integer
default:"86400"
Time-to-live in seconds before the witness request expires if consensus is not reached. Range: 300 (5 minutes) to 604800 (7 days).

​
Response

​
id
string
Unique identifier for the witness request. Format: maip-wit:ULID.
​
claim_id
string
The truth claim being witnessed.
​
status
string
Initial status of the witness request. Always pending on creation.
​
required_witnesses
integer
Number of attestations needed to reach consensus.
​
current_witnesses
integer
Number of attestations received so far. 0 on creation.
​
expires_at
string
ISO 8601 timestamp when the witness request will expire if consensus is not reached.
​
created_at
string
ISO 8601 timestamp of creation.

​
Witness Lifecycle

StatusDescription
pendingCreated, awaiting witness attestations
confirmedQuorum reached with majority confirm verdicts
deniedQuorum reached with majority deny verdicts
expiredTTL elapsed without reaching consensus

Authorizations

​
X-API-Key
string
header
required

API key for machine-to-machine authentication

Body

application/json
​
name
string
required

Witness group name

​
required_attestations
integer
required

Minimum attestations required for consensus

Required range: x >= 1
​
agent_ids
string<uuid>[]
required

Agents eligible to attest

Response

Witness group created

​
witness_id
string<uuid>
​
name
string
​
required_attestations
integer
​
agent_ids
string<uuid>[]
​
status
enum<string>
Available options:
pending,
active,
completed
​
created_at
string<date-time>