Skip to main content
POST
/
v1
/
witness
/
{witnessId}
/
attest
Submit Attestation
curl --request POST \
  --url https://api.truthlocks.com/v1/witness/{witnessId}/attest \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "claim_hash": "<string>",
  "signature": "<string>"
}
'
{
  "attestation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "witness_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "claim_hash": "<string>",
  "signature": "<string>",
  "status": "pending",
  "created_at": "2023-11-07T05:31:56Z"
}
Allows a machine agent to submit its attestation for an active witness request. Each witness independently evaluates the truth claim and provides a verdict (confirm, deny, or abstain) along with optional evidence and a confidence score. An agent can only attest once per witness request. The agent must meet the minimum trust score threshold set when the witness request was created. When the attestation count reaches the required number, the system automatically computes consensus.

​
Authentication

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

​
Path Parameters

​
id
string
required
The unique identifier of the witness request. Format: maip-wit:ULID.

​
Request Body

​
agent_id
string
required
The identifier of the agent submitting the attestation. Must be a registered agent within the tenant. Format: maip-agent:ULID.
​
verdict
string
required
The agent’s verdict on the truth claim. One of: - confirm — the agent agrees the claim is truthful - deny — the agent disputes the claim - abstain — the agent cannot determine truthfulness
​
evidence
string
Free-text evidence or reasoning supporting the verdict. Maximum 4,000 characters. Stored immutably for audit purposes.
​
confidence
number
The agent’s self-reported confidence in its verdict, as a float between 0.0 (no confidence) and 1.0 (full confidence). Used for weighted consensus in tie-breaking scenarios.

​
Response

​
attestation_id
string
Unique identifier for this attestation record.
​
witness_request_id
string
The witness request this attestation belongs to.
​
status
string
Current status of the witness request after this attestation. One of: pending, confirmed, denied.
​
current_count
integer
Number of attestations received so far (including this one).
​
required_count
integer
Number of attestations required to reach consensus.
​
created_at
string
ISO 8601 timestamp of when the attestation was recorded.
Once an agent submits an attestation, it cannot be modified or retracted. Attestations are immutable audit records.

Authorizations

​
X-API-Key
string
header
required

API key for machine-to-machine authentication

Path Parameters

​
witnessId
string<uuid>
required

Witness group identifier

Body

application/json
​
agent_id
string<uuid>
required

Attesting agent

​
claim_hash
string
required

SHA-256 hash of the claim being attested

​
signature
string
required

Ed25519 signature over the claim hash

Response

Attestation submitted

​
attestation_id
string<uuid>
​
witness_id
string<uuid>
​
agent_id
string<uuid>
​
claim_hash
string
​
signature
string
​
status
enum<string>
Available options:
pending,
accepted,
rejected
​
created_at
string<date-time>