Quickstart

Classify text with a hosted model.

POST https://api.truepositive.ai/v1/classify with an organization API key. Model IDs are on Models.

import os
import requests

response = requests.post(
    "https://api.truepositive.ai/v1/classify",
    headers={"Authorization": f"Bearer {os.environ['TRUEPOSITIVE_API_KEY']}"},
    json={"model": "truepositive/moderation", "input": "hello"},
)
print(response.json())

Authentication

Send the key as a Bearer token in Authorization. Keys start with tp_live_ and live in organization settings.

Request

Request body fields
Field	Type	Limits
model	string	A managed model ID such as `truepositive/moderation`
input	string or string[]	One string, or 1–32 strings, each 1–16,384 characters

A batch returns one result per string, in order, billed per item.

Response

200

{
  "id": "req_9f4c2ab1",
  "model": "truepositive/moderation",
  "results": [
    { "index": 0, "scores": { "Safe": 0.98, "Harassment": 0.01 } }
  ],
  "latency_ms": 141,
  "usage": {
    "input_items": 1,
    "cost": { "amount": "0.001000", "currency": "USD" }
  }
}

results[].scores maps labels to 0–1. usage.cost.amount is the USD debit.

Errors

Error

{
  "id": "req_9f4c28d2",
  "error": { "code": "insufficient_credits" }
}

Classify error codes
Status	Code	Meaning
400	bad_request	Malformed JSON, or model/input fields outside the documented limits.
401	unauthorized	Missing, malformed, or revoked organization API key.
402	insufficient_credits	The organization is out of credits. Add credits, then retry.
403	entitlement_required	The organization's plan does not cover this usage.
404	not_found	Unknown path or model ID. Check the model ID on the Models page.
405	method_not_allowed	The endpoint only accepts POST.
409	idempotency_conflict	The Idempotency-Key was already used with a different request body.
409	idempotency_in_progress	A request with the same Idempotency-Key is still processing; retry shortly.
413	payload_too_large	The request body exceeds the accepted size.
500	internal_error	Unexpected server failure. Safe to retry with the same Idempotency-Key.
502	bad_gateway	The model returned an unusable response. Safe to retry with the same Idempotency-Key.
503	unavailable	The model is temporarily unavailable. Safe to retry with the same Idempotency-Key.
503	gateway_disabled	The API is temporarily disabled. Safe to retry with the same Idempotency-Key.
504	gateway_timeout	The model did not respond in time. Safe to retry with the same Idempotency-Key.

Idempotency

Send Idempotency-Key when you might retry. Same body replays and is not charged again. A different body returns idempotency_conflict. Keys are up to 128 characters.

curl -X POST https://api.truepositive.ai/v1/classify \
  -H "Authorization: Bearer $TRUEPOSITIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-4187-first-check" \
  -d '{ "model": "truepositive/moderation", "input": "hello" }'