Introduction

Truthify API Reference

The Truthify API lets you programmatically analyze content for positive attributes, negative attributes, and logical fallacies — producing integrity scores for any named individual.

BASE URL https://api.truthify.io/v1

All requests and responses use JSON. All endpoints require authentication via your API key. Responses follow predictable patterns — successes return the resource, errors return a message field describing what went wrong.

Authentication

API Key Authentication

Every request to the Truthify API must include your API key in the x-api-key HTTP header. Your key is issued when you create an account and scoped to that account — all persons and content you create are automatically associated with it.

Where to find your API key

Your API key is provisioned when you create an smb, corporate, or enterprise account and is accessible via your account dashboard. You can rotate it at any time via the POST /rotate_api_key endpoint. Your old key is immediately invalidated on rotation.

Header format

Header
Description
x-api-key required
Your Truthify API key. Must be present on every request.
Keep your key secret

API keys carry full account access. Do not log them, expose them in client-side code, or commit them to source control. Use environment variables or a secrets manager.

Authentication errors

401 Missing or invalid API key
403 Valid key but insufficient permissions
Example request 
curl https://api.truthify.io/v1/new_person \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "personName": "Jane Smith" }'
401 — missing key 401 
{
  "message": "Unauthorized. Valid API key or authentication token required."
}
Errors & Rate Limits

Error Responses

All errors return a JSON body with a single message field. HTTP status codes follow standard conventions.

Status
Meaning
200
Success.
400
Bad request — missing or invalid fields in the body.
401
Unauthorized — API key missing, invalid, or not linked to an account.
404
Not found — the requested resource does not exist.
500
Internal server error — something went wrong on our side.

Rate Limits

Limits apply per account. Exceeding a limit returns a 429 response.

Endpoint
SMB
Corporate
Enterprise
POST /new_person
1 / min
10 / min
100 / min
POST /upload_content
10 / min
100 / min
1,000 / min
GET /get_person/{personId}
100 / min
1,000 / min
10,000 / min
GET /get_content/{personId}/{contentId}
100 / min
1,000 / min
10,000 / min
Error response shape 4xx / 5xx 
{
  "message": "Human-readable description of the error."
}
400 — missing required field 400 
{
  "message": "Missing personName in request"
}
500 — server error 500 
{
  "message": "Internal server error"
}
Persons
POST /new_person

Creates a new person profile in your account. Returns a personId that you'll use to associate content with this person and retrieve their analysis later.

Request body

Field
Description
personName string required
Full name of the person to create.
section string optional
Organization or company the person belongs to (e.g. "Acme Corp").
position string optional
The person's job title or role (e.g. "CFO").
group string optional
Category or group for organizational purposes (e.g. "business").

Response

200Person created successfully
400Missing or invalid personName
401Invalid or missing API key
500Server error creating person
Request 
curl -X POST https://api.truthify.io/v1/new_person \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "personName": "Jane Smith",
    "section": "Acme Corp",
    "position": "CFO",
    "group": "business"
  }'
200 — Success 200 
{
  "personId": "c25c104e-7686-42c2-9f80-772b52506514"
}
400 — Missing personName 400 
{
  "message": "Missing personName in request"
}
401 — Unauthorized 401 
{
  "message": "Unauthorized. Valid API key or authentication token required."
}
Content
POST /upload_content
⚡ 10 requests / minute

Submits text content for AI analysis against a specific person. The content is queued immediately and analyzed asynchronously — use GET /get_content to poll for results.

Async processing

Analysis typically completes within 30–60 seconds. While processing, GET /get_content returns "status": "analyzing". Poll until you see the full result object.

Request body

Field
Description
personId string required
The personId returned from POST /new_person. Associates this content with the person being analyzed.
content string required
The raw text to analyze — interview transcript, speech, article, or any other text attributed to the person.
categoryName string required
The type of content being submitted. Affects how the AI frames its analysis.
initiation interview balanced consistency
contentTitle string required
A short descriptive label for this piece of content (e.g. "Q3 Earnings Call Transcript"). Used in reports and the dashboard.

Response

200Content accepted and queued for analysis
400Missing required field(s) in body
401Invalid or missing API key
500Server error storing content
Request 
curl -X POST https://api.truthify.io/v1/upload_content \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "personId": "c25c104e-7686-42c2-9f80-772b52506514",
    "categoryName": "interview",
    "contentTitle": "Q3 Earnings Call Transcript",
    "content": "Today we exceeded our revenue targets by 40%..."
  }'
200 — Queued successfully 200 
{
  "message":      "Content uploaded successfully and queued for analysis",
  "contentId":    "5326022d-004f-4904-88b4-e6c4f41e83ad",
  "personId":     "c25c104e-7686-42c2-9f80-772b52506514",
  "categoryName": "interview",
  "contentTitle": "Q3 Earnings Call Transcript",
  "wordCount":    142,
  "_meta": {
    "auth_type":   "api_key",
    "request_id":  "fbaba386-66c3-4195-bda2-eea0b4090530"
  }
}
400 — Missing required fields 400 
{
  "message": "Invalid request. personId and content are required."
}
Persons
GET /get_person/{personId}
⚡ 100 requests / minute

Returns the complete profile for a person — including their overall integrity score and the full list of content reports that have been analyzed against them.

Path parameters

Parameter
Description
personId string required
The UUID of the person, returned by POST /new_person.

Response fields

Field
Description
personIdstring
Unique identifier for this person.
personNamestring
Full name provided at creation.
sectionstring
Organization name, if provided.
positionstring
Job title, if provided.
overallScorenumber
Aggregate integrity score across all analyzed content (0–100). 0 if no content has been analyzed yet.
reportsarray
Array of content report summaries. Each item contains contentId, contentTitle, categoryName, overallScore, and status.
createdAtstring
ISO 8601 timestamp of when the person was created.

Response statuses

200Person found — returns full profile
401Invalid or missing API key
404No person found with that ID
500Server error retrieving profile
Request 
curl https://api.truthify.io/v1/get_person/c25c104e-7686-42c2-9f80-772b52506514 \
  -H "x-api-key: YOUR_API_KEY"
200 — Success 200 
{
  "personId":    "c25c104e-7686-42c2-9f80-772b52506514",
  "personName":  "Jane Smith",
  "accountId":   "2317357a-a8ec-42c7-b9f6-e0698263fa6e",
  "section":     "Acme Corp",
  "position":    "CFO",
  "group":       "business",
  "overallScore":72,
  "createdAt":   "2025-11-08T19:35:59.595133",
  "reports": [
    {
      "contentId":    "5326022d-004f-4904-88b4-e6c4f41e83ad",
      "contentTitle": "Q3 Earnings Call Transcript",
      "categoryName": "interview",
      "overallScore": 72,
      "wordCount":    142,
      "status":       "completed",
      "createdAt":    1762632815
    }
  ]
}
404 — Not found 404 
{
  "message": "Person not found"
}
Content
GET /get_content/{personId}/{contentId}
⚡ 100 requests / minute

Returns the full AI analysis for a specific piece of content. If analysis is still running, the response has "status": "analyzing" — poll every few seconds until you receive the full result.

Polling pattern

After calling POST /upload_content, poll GET /get_content every 5 seconds. When the status field is absent and summary is present, analysis is complete.

Path parameters

Parameter
Description
personId string required
The UUID of the person this content belongs to.
contentId string required
The UUID of the content, returned by POST /upload_content.

Response fields (completed)

Field
Description
summary.executive_summarystring
A high-level narrative summary of the analysis findings.
summary.positiveScorenumber
Average score (0–100) across all positive attribute analyses.
summary.negativeScorenumber
Average score (0–100) across all negative attribute analyses (higher = fewer negative signals).
summary.overallScorenumber
Combined integrity score (0–100) for this piece of content.
summary.conclusionsobject
Contains strengths, areas_of_development, areas_of_excellence, and overall_impression arrays/strings.
detail.positive_attributesarray
Per-attribute breakdown: analysisName, categoryScore, classification (low/medium/high), summary, keyindicators, evidences.
detail.negative_attributesarray
Same shape as positive attributes. Covers: Exaggeration_of_Fear, Exaggeration_of_Excitement, Unnecessary_Volunteering_of_Emotions, Deflection, Triangulation, Formal_Logical_Fallacies, Informal_Logical_Fallacies.

Response statuses

200Analysis complete — full result returned
200Still processing — "status": "analyzing"
401Invalid or missing API key
404Content or person not found
500Server error retrieving content
Request 
curl https://api.truthify.io/v1/get_content/c25c104e-7686-42c2-9f80-772b52506514/5326022d-004f-4904-88b4-e6c4f41e83ad \
  -H "x-api-key: YOUR_API_KEY"
200 — Still analyzing Pending 
{
  "contentId": "5326022d-004f-4904-88b4-e6c4f41e83ad",
  "personId":  "c25c104e-7686-42c2-9f80-772b52506514",
  "status":    "analyzing"
}
200 — Analysis complete 200 
{
  "contentId":    "5326022d-004f-4904-88b4-e6c4f41e83ad",
  "personId":     "c25c104e-7686-42c2-9f80-772b52506514",
  "contentTitle": "Q3 Earnings Call Transcript",
  "categoryName": "interview",
  "createdAt":    1762632815,
  "summary": {
    "executive_summary": "The speaker demonstrates high consistency and direct communication with minimal deflection or emotional signaling.",
    "positiveScore": 33,
    "negativeScore": 96,
    "overallScore":  65,
    "conclusions": {
      "overall_integity_profile": "Strong integrity profile...",
      "strengths": [
        "Outstanding consistency (90.0)",
        "Direct and focused communication with low deflection (15.37)"
      ],
      "areas_of_development": [
        "Enhancing balance in communication (Balanced: 15.0)"
      ],
      "overall_impression": "Profile demonstrates clear, consistent integrity and reliability."
    }
  },
  "detail": {
    "positive_attributes": [
      {
        "analysisName":       "Consistency",
        "categoryScore":      90.0,
        "classification":     "high",
        "keyindicators":      ["understanding this correctly"],
        "integritySignificance":"Clear query demonstrates coherent intent.",
        "summary":           "Speaker demonstrates consistent, coherent intent.",
        "evidences":         ["Today we exceeded our revenue targets..."]
      }
    ],
    "negative_attributes": [
      {
        "analysisName":   "Deflection",
        "categoryScore":  15.37,
        "classification": "low",
        "keyindicators":  ["direct engagement"],
        "summary":       "Low deflection shows direct engagement.",
        "evidences":     ["Today we exceeded our revenue targets..."]
      }
    ]
  }
}
404 — Not found 404 
{
  "contentId": "5326022d-004f-4904-88b4-e6c4f41e83ad",
  "personId":  "c25c104e-7686-42c2-9f80-772b52506514",
  "status":    "not_found"
}
Content
DELETE /remove_content/{personId}/{contentId}
⚡ 10 requests / minute

Permanently deletes a content record and all associated S3 objects (analysis JSON and raw text). This action is irreversible.

Ownership required

The personId must belong to the account associated with the API key. Attempting to delete another account's content returns 404.

Path parameters

Parameter
Description
personId string required
The UUID of the person the content belongs to.
contentId string required
The UUID of the content to delete, returned by POST /upload_content.

Response

200Content deleted successfully
401Invalid or missing API key
404Content not found or person does not belong to this account
500Server error
Request 
curl -X DELETE https://api.truthify.io/v1/remove_content/{personId}/{contentId} \
  -H "x-api-key: YOUR_API_KEY"
200 — Success 200 
{
  "message":   "Content removed successfully",
  "contentId": "5326022d-004f-4904-88b4-e6c4f41e83ad",
  "personId":  "c25c104e-7686-42c2-9f80-772b52506514"
}
404 — Not found 404 
{
  "message": "Content not found"
}
Persons
DELETE /remove_person/{personId}
⚡ 1 request / minute

Permanently deletes a person record and all associated content and S3 data for that person. This action is irreversible.

Ownership required

The personId must belong to the account associated with the API key. Attempting to delete another account's person returns 404.

Path parameters

Parameter
Description
personId string required
The UUID of the person to delete, returned by POST /new_person.

Response

200Person and all associated data deleted
401Invalid or missing API key
404Person not found or does not belong to this account
500Server error
Request 
curl -X DELETE https://api.truthify.io/v1/remove_person/{personId} \
  -H "x-api-key: YOUR_API_KEY"
200 — Success 200 
{
  "message":  "Person removed successfully",
  "personId": "c25c104e-7686-42c2-9f80-772b52506514"
}
404 — Not found 404 
{
  "message": "Person not found or access denied"
}
Truthify API — All rights reserved. Base URL: https://api.truthify.io/v1