Skip to main content
POST
/
v1
/
truth
Create Truth Claim
curl --request POST \
  --url https://api.truthlocks.com/v1/truth \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "claim_type": "<string>",
  "payload": {},
  "evidence": [
    {}
  ]
}
'
{
  "claim_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "claim_type": "<string>",
  "payload": {},
  "evidence": [
    {}
  ],
  "status": "pending",
  "receipt_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "attestations": [
    {
      "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"
    }
  ],
  "verified_at": "2023-11-07T05:31:56Z",
  "created_at": "2023-11-07T05:31:56Z"
}
Creates a new truth claim — a formal assertion made by a machine agent about a subject. Truth claims are the foundational data objects in the MAIP verification pipeline. Once created, a claim can be routed through witness verification, AI analysis, or human review before receiving a final determination. Claims are immutable once created. The status field tracks the claim through its lifecycle from pending to a terminal state (verified, disputed, or rejected). A receipt is automatically minted when the claim reaches a terminal state.

​
Authentication

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

​
Request Body

​
agent_id
string
required
The identifier of the agent making the claim. The agent must be registered and active within the tenant. Format: maip-agent:ULID.
​
claim_type
string
required
Classification of the claim. Common types include: - identity — claims about agent or entity identity - integrity — claims about data or document integrity - provenance — claims about data origin or chain of custody - compliance — claims about regulatory compliance - capability — claims about an agent’s capabilities or certifications
​
subject
string
required
The entity or resource the claim is about. This could be an agent ID, document hash, URL, or any URI-formatted identifier.
​
assertion
string
required
The human-readable assertion being made. Maximum 2,000 characters. This is the core statement that will be verified.
​
evidence_urls
string[]
List of URLs pointing to supporting evidence for the claim. Each URL must be HTTPS and accessible to the verification pipeline.
​
confidence
number
The claiming agent’s self-reported confidence in the assertion, as a float between 0.0 and 1.0. This does not influence verification but is recorded for analytics.
​
metadata
object
Arbitrary key-value metadata to attach to the claim. Useful for correlation IDs, source system references, or domain-specific context. Maximum 10 keys, 1 KB total.

​
Response

​
id
string
Unique identifier for the truth claim. Format: maip-tc:ULID.
​
agent_id
string
The agent that created the claim.
​
claim_type
string
The classification of the claim.
​
subject
string
The entity or resource the claim is about.
​
assertion
string
The assertion being made.
​
status
string
Initial status. Always pending on creation.
​
created_at
string
ISO 8601 timestamp of creation.

​
Claim Lifecycle

StatusDescription
pendingCreated, awaiting verification
verifyingVerification in progress (witness, AI, or human)
verifiedClaim confirmed as truthful
disputedClaim contested — conflicting evidence found
rejectedClaim determined to be false

Authorizations

​
X-API-Key
string
header
required

API key for machine-to-machine authentication

Body

application/json
​
agent_id
string<uuid>
required

Claiming agent

​
claim_type
string
required

Classification of the claim (e.g. data_integrity, model_accuracy)

​
payload
object
required

Claim payload

​
evidence
object[]

Supporting evidence objects

Response

Truth claim created

​
claim_id
string<uuid>
​
agent_id
string<uuid>
​
claim_type
string
​
payload
object
​
evidence
object[]
​
status
enum<string>
Available options:
pending,
verified,
rejected,
expired
​
receipt_id
string<uuid>
​
attestations
object[]
​
verified_at
string<date-time>
​
created_at
string<date-time>