Skip to main content

API Reference

Method signatures and parameters for the Respectify client libraries. For response field details, see the Schema Reference.

Methods​

MethodDescription
ConstructorCreate a client instance
init_topic_from_textInitialize a topic from text content
init_topic_from_urlInitialize a topic from a URL
evaluate_commentFull comment quality analysis
check_spamSpam detection
check_relevanceOn-topic and banned topics check
check_dogwhistleCoded language detection
megacallMultiple analyses in one call
check_user_credentialsVerify API credentials
runExecute event loop (PHP only)
import { RespectifyClient } from "@respectify/client";

All methods are async and return promises. The client uses the native fetch API (Node.js 18+).

Constructor​

RespectifyClient

const client = new RespectifyClient({
  email: string,
  apiKey: string,
  baseUrl?: string,    // defaults to "https://app.respectify.ai"
  version?: string,    // defaults to "0.2"
  timeout?: number,    // defaults to 30000 (ms)
  website?: string
});
ParameterDescription
emailYour registered email address
api_key / apiKey / $apiKeyYour API key from the dashboard
base_url / baseUrl / $baseUrlOverride the API endpoint (optional)
versionAPI version, defaults to 0.2 (optional)
timeoutRequest timeout in seconds (Python) or milliseconds (TypeScript)
websiteYour website domain, included in API calls (optional)

Initialize Topic from Text​

Initialize a topic from plain text or Markdown content. You can also initialize from a URL instead. See examples of initializing topics.

initTopicFromText

async initTopicFromText(
  text: string,
  topicDescription?: string
): Promise<InitTopicResponse>
const response = await client.initTopicFromText(
  "Article content here...",
  "Optional context about the article"
);
const articleId = response.article_id;
ParameterDescription
textThe text content to initialize the topic from
topic_description / topicDescriptionAdditional context about the topic (optional)

Returns: InitTopicResponse containing the article_id UUID.

Initialize Topic from URL​

Initialize a topic from a URL pointing to HTML, Markdown, PDF, or plain text. You can also initialize from text instead. See examples of initializing topics.

initTopicFromUrl

async initTopicFromUrl(
  url: string,
  topicDescription?: string
): Promise<InitTopicResponse>
const response = await client.initTopicFromUrl(
  "https://example.com/article",
  "Blog post about AI safety"
);
const articleId = response.article_id;
ParameterDescription
urlURL to fetch content from (must be publicly accessible)
topic_description / topicDescriptionAdditional context about the topic (optional)

Returns: InitTopicResponse containing the article_id UUID.

Throws: UnsupportedMediaTypeError / UnsupportedMediaTypeException if the URL points to an unsupported format (images, video, .docx, etc).

Evaluate Comment​

Evaluates a comment in the context of the article or topic the conversation is about, and optionally the comment it is replying to. This is Respectify's main API and the one you will likely call the most.

It returns:

  • A list of any common logical fallacies that seem present, with the goal of educating the commenter on traps they may be falling into. This includes the fallacy name, the quoted part of their comment that demonstrates it, an explanation, and sometimes a suggested rewrite (only if the commenter's intent was very clear).

  • Any objectionable or rude phrases, including what they are, why we assessed them as such, and very rarely a suggested rewrite.

  • Any negative tone phrases. These aren't objectionable or rude, but are phrases that don't contribute to the conversation. Note that Respectify encourages friendly (genuine, well-intentioned) disagreement and healthy sharing of different opinions and views. Sometimes disagreement can be done in an unhealthy way and this section identifies those.

  • If the comment appears 'low effort' (usually short comments that don't add to the conversation, e.g., "me too").

  • Toxicity score (0-1): Targets attacks on people, not ideas. Attacking a policy harshly scores low; attacking the person making it scores high.

  • health_items: For each comment health item not turned off (the nine problem categories and quality), a score from 1 to 5, the minimum its level accepts, and whether it is acceptable. The quality score, how well the comment engages and contributes to the conversation, is health_items.quality.score.

  • An overall score (1-5): Comment health, combining quality with the worst problem found. health_score gives the same as a number from 1.0 to 5.0.

  • exceeds_tolerance: Whether the comment is beyond what your site's tolerances accept. Each finding also carries a severity, and each phrase a category. Use exceeds_tolerance, rather than toxicity_score or overall_score alone, to decide what to do with a comment.

The idea is to use this not to censor but to educate and encourage better discussion. We hope that over time, as a result of feedback, your users will proactively write better comments without needing to be prompted.

See examples of scoring comments.

evaluateComment

async evaluateComment(
  comment: string,
  articleId: string,
  replyToComment?: string,
  tolerances?: ModerationTolerances
): Promise<CommentScore>
const result = await client.evaluateComment(
  "This is a thoughtful response...",
  articleId
);
console.log(`Comment health: ${result.overall_score}/5`);
console.log(`Toxicity: ${result.toxicity_score}`);
ParameterDescription
commentThe comment text to evaluate
article_id / articleId / $articleContextIdUUID from topic initialization
reply_to_comment / replyToComment / $replyToCommentThe parent comment, for context (optional)
tolerances / tolerances / $tolerancesThe comment health level for each item named; items left out are standard (optional). Items: the nine problem categories and quality. Levels: off, permissive, relaxed, standard, strict, zero_tolerance; floored categories accept only standard or stricter. REST: send the request as JSON to include it.

Returns: CommentScore with comment health (health_items, health_score, overall_score), fallacies, tone analysis, and exceeds_tolerance.

Check Spam​

Decides if a comment is spam. The article context is optional; if omitted, the comment is evaluated for spam on its own.

The definition of spam is broad: from obvious commercial sales, through to probable malware (signs of it in the comment, but do not rely on this for security), through to SEO or link spam, phishing attempts, crypto scams, fake reviews, AI-generated nonsense, and much more.

There are three outcomes: spam (is_spam true: delete it), suspected spam (suspected_spam true: send it back to the commenter with the suggestion), and not spam (publish it). See First-Pass Screening.

See examples of spam detection.

checkSpam

async checkSpam(
  comment: string,
  articleId?: string
): Promise<SpamDetectionResult>
const result = await client.checkSpam(comment, articleId);
if (result.is_spam) {
  console.log(`Spam detected: ${result.reasoning}`);
}
ParameterDescription
commentThe comment text to check.
articleIdUUID from topic initialization (optional).

Returns: SpamDetectionResult with is_spam, suspected_spam, suggestion and reasoning.

Check Relevance​

Evaluates the relevance of a comment to the article it's commenting on, plus checks for topics the site admin does not want discussed.

This is intended to help keep conversations relevant or on-topic, plus to allow site admins to disallow conversation on specific topics. (Our use case here is how legitimate-sounding comments with dog whistles or what-abouts can simply be disallowed.)

Returns two assessments, each with a boolean result and confidence score (0-1):

  • On-topic: Is the comment plausibly related to the article? Even poor-quality comments are marked on-topic if they're about the subject.
  • Banned topics: Does the comment discuss any topics from your banned list? Also includes what proportion of the comment is about banned topics.

See examples of relevance checking.

checkRelevance

async checkRelevance(
  comment: string,
  articleId: string,
  bannedTopics?: string[]
): Promise<CommentRelevanceResult>
const result = await client.checkRelevance(
  comment,
  articleId,
  ["politics", "religion"]
);
console.log(`On topic: ${result.on_topic.on_topic}`);
ParameterDescription
commentThe comment text to check
article_id / articleId / $articleContextIdUUID from topic initialization
banned_topics / bannedTopics / $bannedTopicsTopics to flag (optional)

Returns: CommentRelevanceResult with on-topic and banned topics analysis.

Check Dogwhistle​

Detects coded language (dogwhistles) that appears innocuous but carries hidden meanings to specific groups.

Dogwhistles can be subtle: numbers with hidden meanings (like "88" or "1488"), coded racial terms ("urban youths", "globalists"), extremist phrases, conspiracy markers ("just asking questions", "do your research"), and more. The detection is context-aware: discussing renewable energy policy is legitimate, but "green agenda pushed by globalists" is a dogwhistle.

Returns:

  • Detection: Whether dogwhistles were found, with reasoning and confidence (0-1).
  • Details (if detected): The specific terms found, their categories, how subtle they are (0-1), and harm potential (0-1).

You can provide sensitive_topics to focus detection on specific areas, and dogwhistle_examples if you know specific coded phrases used in your community.

See examples of dogwhistle detection.

checkDogwhistle

async checkDogwhistle(
  comment: string,
  articleId: string,
  sensitiveTopics?: string[],
  dogwhistleExamples?: string[]
): Promise<DogwhistleResult>
const result = await client.checkDogwhistle(
  comment,
  articleId,
  ["extremism"]
);
if (result.detection.dogwhistles_detected) {
  console.log(`Dogwhistle detected: ${result.details?.dogwhistle_terms}`);
}
ParameterDescription
commentThe comment text to analyze
article_id / articleId / $articleContextIdUUID from topic initialization
sensitive_topics / sensitiveTopics / $sensitiveTopicsTopics to watch for (optional)
dogwhistle_examples / dogwhistleExamples / $dogwhistleExamplesKnown examples to detect (optional)

Returns: DogwhistleResult with detection status and details.

Megacall​

Run any combination of comment scoring, spam detection, relevance checking, and dogwhistle detection in a single API call.

A single request is faster than multiple requests for each kind of analysis. It's also more cost-effective: you're charged for fewer API calls than the individual features in the megacall.

Each analysis type is optional. Only request what you need to minimize latency and cost. At least one feature flag must be set.

See examples of using megacall and selecting which checks to run.

megacall

async megacall(options: MegacallOptions): Promise<MegaCallResult>
const result = await client.megacall({
  comment: comment,
  articleId: articleId,
  includeSpam: true,
  includeCommentScore: true,
  includeRelevance: true,
});

if (result.spam_check) {
  console.log(`Spam: ${result.spam_check.is_spam}`);
}
if (result.comment_score) {
  console.log(`Score: ${result.comment_score.overall_score}`);
}
ParameterDescription
commentThe comment text to analyze
article_id / articleId / $articleContextIdUUID from topic initialization
include_* / include* / $servicesWhich analyses to run
banned_topics / bannedTopics / $bannedTopicsFor relevance check (optional)
sensitive_topics / sensitiveTopics / $sensitiveTopicsFor dogwhistle check (optional)
dogwhistle_examples / dogwhistleExamples / $dogwhistleExamplesFor dogwhistle check (optional)
tolerances / tolerances / $tolerancesThe comment health level for each item named, for the comment score; items left out are standard (optional). Used only when the comment score is requested.

Returns: MegaCallResult containing only the requested analyses (others are null). When spam is requested and first-pass screening is confident the comment is spam, only spam_check is returned and every other analysis is null (a suspected-spam comment is not spam, so every requested analysis is returned); see First-Pass Screening.

Check User Credentials​

Verify your API credentials and get subscription status. See Verifying Credentials.

checkUserCredentials

async checkUserCredentials(): Promise<UserCheckResponse>
const result = await client.checkUserCredentials();
console.log(`Active: ${result.active}`);
console.log(`Plan: ${result.plan_name}`);
console.log(`Endpoints: ${result.allowed_endpoints}`);

Returns: UserCheckResponse with subscription status, plan details, and allowed endpoints.

Run Event Loop (PHP only)​

Execute the ReactPHP event loop. You must call this after API methods for promises to resolve.

run

public function run(): void
$client->checkSpam($comment, $articleId)->then(/* ... */);
$client->evaluateComment($articleId, $comment)->then(/* ... */);
$client->run(); // Execute all pending requests

See Also​