> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truthlocks.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Truth Claim
> Submit a new truth claim from a machine agent for verification
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
The identifier of the agent making the claim. The agent must be registered and
active within the tenant. Format: `maip-agent:ULID`.
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
The entity or resource the claim is about. This could be an agent ID, document
hash, URL, or any URI-formatted identifier.
The human-readable assertion being made. Maximum 2,000 characters. This is the
core statement that will be verified.
List of URLs pointing to supporting evidence for the claim. Each URL must be
HTTPS and accessible to the verification pipeline.
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.
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
Unique identifier for the truth claim. Format: `maip-tc:ULID`.
The agent that created the claim.
The classification of the claim.
The entity or resource the claim is about.
The assertion being made.
Initial status. Always `pending` on creation.
ISO 8601 timestamp of creation.
### Claim Lifecycle
| Status | Description |
| :---------- | :----------------------------------------------- |
| `pending` | Created, awaiting verification |
| `verifying` | Verification in progress (witness, AI, or human) |
| `verified` | Claim confirmed as truthful |
| `disputed` | Claim contested -- conflicting evidence found |
| `rejected` | Claim determined to be false |
## OpenAPI
````yaml mint-openapi.yaml POST /v1/truth/claim
openapi: 3.0.3
info:
title: Truthlocks API
description: >
Truthlocks is a universal verification infrastructure for documents,
credentials, and digital assets.
This specification defines the canonical API for interacting with Truthlocks
services.
## Base URLs
- **Production**: `https://api.truthlocks.com`
- **Sandbox**: `https://sandbox-api.truthlocks.com`
## Authentication
- **API Keys**: Use `X-API-Key` header for machine-to-machine operations
- **Bearer Tokens**: Use `Authorization: Bearer ` for user-initiated
operations
## Tenant Identity
In production, tenant identity is derived from the authenticated context
(API key or JWT).
The `X-Tenant-ID` header is ignored in production to prevent spoofing.
version: 1.0.0
contact:
name: Truthlocks Support
url: https://truthlocks.com/support
email: support@truthlocks.com
servers:
- url: https://api.truthlocks.com
description: Production API
- url: https://sandbox-api.truthlocks.com
description: Sandbox Environment
security:
- APIKey: []
tags:
- name: Authentication
description: API key and token management
- name: Issuers
description: Issuer registration and trust management
- name: Keys
description: Cryptographic key management for issuers
- name: Attestations
description: Attestation lifecycle (mint, revoke, supersede)
- name: Verification
description: Attestation verification and proof bundles
- name: Governance
description: Issuer governance workflows (admin only)
- name: Identity
description: Organization, user, and role management
- name: Audit
description: Audit event queries
- name: Platform
description: Platform administration (super admin only)
- name: Platform Review
description: Staff review workflows for issuer applications
- name: Tenant Console
description: Tenant profile and lifecycle endpoints
- name: Health
description: Service health and readiness endpoints
- name: Risk
description: Risk signal ingestion and fraud detection
- name: Risk Enforcement
description: Risk enforcement actions — block, challenge, quarantine, and configuration
- name: Billing
description: Billing, subscription, and addon management
- name: Machine Identity
description: >-
Machine Agent Identity Protocol (MAIP) — agent registration, sessions,
trust, witness, compliance, orchestration, and observability
externalDocs:
description: Transparency read-only API (separate service spec)
url: >-
https://github.com/truthlocks/truthlock/blob/main/docs/transparency/openapi.yaml
paths:
/v1/truth/claim:
post:
tags:
- Machine Identity
summary: Create Truth Claim
description: >
Creates a new truth claim with supporting evidence. A receipt is
generated
for auditability and the claim enters a verification pipeline.
operationId: maip.truth.create
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- agent_id
- claim_type
- payload
properties:
agent_id:
type: string
format: uuid
description: Claiming agent
claim_type:
type: string
description: >-
Classification of the claim (e.g. data_integrity,
model_accuracy)
payload:
type: object
additionalProperties: true
description: Claim payload
evidence:
type: array
items:
type: object
additionalProperties: true
description: Supporting evidence objects
responses:
'201':
description: Truth claim created
content:
application/json:
schema:
$ref: '#/components/schemas/MaipTruthClaim'
'400':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'401':
description: Authentication required
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'429':
description: Rate limit exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
security:
- APIKey: []
components:
schemas:
MaipTruthClaim:
type: object
properties:
claim_id:
type: string
format: uuid
agent_id:
type: string
format: uuid
claim_type:
type: string
payload:
type: object
additionalProperties: true
evidence:
type: array
items:
type: object
additionalProperties: true
status:
type: string
enum:
- pending
- verified
- rejected
- expired
receipt_id:
type: string
format: uuid
attestations:
type: array
items:
$ref: '#/components/schemas/MaipAttestation'
verified_at:
type: string
format: date-time
created_at:
type: string
format: date-time
ErrorEnvelope:
type: object
required:
- code
- message
- http_status
properties:
code:
type: string
description: Machine-readable error code
enum:
- AUTH_REQUIRED
- AUTH_INVALID
- PERMISSION_DENIED
- TENANT_IDENTITY_UNVERIFIED
- NOT_FOUND
- VALIDATION_ERROR
- CONFLICT
- PAYLOAD_TOO_LARGE
- RATE_LIMIT_EXCEEDED
- QUOTA_EXCEEDED
- SERVICE_UNAVAILABLE
- INTERNAL_ERROR
message:
type: string
description: Human-readable error message
http_status:
type: integer
description: HTTP status code
retry_after_ms:
type: integer
description: Milliseconds to wait before retrying (for rate limits)
details:
type: object
description: Additional error context
example:
code: AUTH_REQUIRED
message: Authentication required
http_status: 401
MaipAttestation:
type: object
properties:
attestation_id:
type: string
format: uuid
witness_id:
type: string
format: uuid
agent_id:
type: string
format: uuid
claim_hash:
type: string
signature:
type: string
status:
type: string
enum:
- pending
- accepted
- rejected
created_at:
type: string
format: date-time
securitySchemes:
APIKey:
type: apiKey
in: header
name: X-API-Key
description: API key for machine-to-machine authentication
````