API Documentation

Comprehensive Guide and Technical Details for Seamless Integration

Authentication

Every endpoint below accepts either of two authentication methods — use whichever fits your integration:

  • X-Domain header — set it to the domain registered to your account (e.g. example.com).
  • Authorization: Bearer <key> header (or equivalently X-Api-Key: <key>) — an API key generated from your dashboard. Required for the Zapier integration, and generally preferred since a domain name isn't a real secret.

Both methods work interchangeably; you don't need to switch an existing X-Domain integration over to an API key. To verify a key or check your remaining quota without spending any of it, call GET https://api.cloudants.io/whoami/v1 with either auth method — it returns {"domain", "plan", "quota_included", "hits", "verification_blocks_remaining"}.

1. NSFW Detection API

Method: POST

Endpoint: https://api.cloudants.io/nsfw/v1

Note: Ensure the URL does not have a trailing slash and authenticate with either the X-Domain header or an API key (see Authentication above).

Request Parameters:

For a Single Image:
{
    "image_urls": [
      "https://image-path.com"
    ]
  }
For Multiple Images:
{
    "image_urls": [
      "https://image-path.com",
      "https://image-path2.com"
    ]
  }

Response Examples:

For a Single Image:
[
    {"image_url":"https://image-path.com","is_nsfw":true,"is_suggestive":false}
  ]
For Multiple Images:
[
    {"image_url":"https://image-path.com","is_nsfw":true,"is_suggestive":false},
    {"image_url":"https://image-path2.com","is_nsfw":false,"is_suggestive":true}
  ]

Usage: is_nsfw flags unambiguous exposed nudity. is_suggestive flags a separate, lower-severity tier — content like swimwear or lingerie photos that isn't nudity but may still warrant review depending on your platform's policy. Most integrations only need to check is_nsfw; is_suggestive is there for platforms that want a stricter bar.

2. Face Detection API

Method: POST

Endpoint: https://api.cloudants.io/face-detect/v1

Note: Ensure the URL does not have a trailing slash and authenticate with either the X-Domain header or an API key (see Authentication above).

Request Parameters:

For a Single Image:
{
    "image_urls": [
      "https://image-path.com"
    ]
  }
For Multiple Images:
{
    "image_urls": [
      "https://image-path.com",
      "https://image-path2.com"
    ]
  }

Response Examples:

For a Single Image:
[
    {"image_url":"https://image-path.com","is_face":true,"is_nsfw":true}
  ]
For Multiple Images:
[
    {"image_url":"https://image-path.com","is_face":true,"is_nsfw":true},
    {"image_url":"https://image-path2.com","is_face":true,"is_nsfw":false}
  ]

Usage: This API detects whether an image contains a face and whether the image is NSFW. The is_face field indicates the presence of a face, while is_nsfw determines if the image is NSFW.

3. Nudity Detection API

Method: POST

Endpoint: https://api.cloudants.io/nudity-detect/v1

Note: Ensure the URL does not have a trailing slash and authenticate with either the X-Domain header or an API key (see Authentication above).

Request Parameters:

For a Single Image:
{
    "image_urls": [
      "https://image-path.com"
    ]
  }
For Multiple Images:
{
    "image_urls": [
      "https://image-path.com",
      "https://image-path2.com"
    ]
  }

Response Examples:

For a Single Image:
[
    {"image_url":"https://image-path.com","is_nude":true,"total_nudity_score":1.3375419974327087}
  ]
For Multiple Images:
[
    {"image_url":"https://image-path.com","is_nude":true,"total_nudity_score":1.3375419974327087},
    {"image_url":"https://image-path2.com","is_nude":false,"total_nudity_score":0}
  ]

Usage: The is_nude field indicates whether the image contains nudity. The total_nudity_score provides a numeric score representing the degree of nudity, which can be used to implement custom logic based on the score.

4. Image Properties API

Method: POST

Endpoint: https://api.cloudants.io/img-prop/v1

Note: Ensure the URL does not have a trailing slash and authenticate with either the X-Domain header or an API key (see Authentication above).

Request Parameters:

For a Single Image:
{
    "image_urls": [
      "https://image-path.com"
    ]
  }
For Multiple Images:
{
    "image_urls": [
      "https://image-path.com",
      "https://image-path2.com"
    ]
  }

Response Examples:

For a Single Image:
[
    [
      {"class":"FACE_FEMALE","score":0.8654655814170837,"box":[267,25,127,120]},
      {"class":"FEMALE_BREAST_EXPOSED","score":0.7974921464920044,"box":[340,199,139,102]},
      {"class":"ARMPITS_EXPOSED","score":0.7133167386054993,"box":[460,196,55,60]},
      {"class":"BELLY_EXPOSED","score":0.6663662195205688,"box":[251,316,156,133]},
      {"class":"FEMALE_BREAST_EXPOSED","score":0.5400498509407043,"box":[226,223,114,100]}
    ]
  ]
For Multiple Images:
[
    [
      {"class":"FACE_FEMALE","score":0.8654655814170837,"box":[267,25,127,120]},
      {"class":"FEMALE_BREAST_EXPOSED","score":0.7974921464920044,"box":[340,199,139,102]},
      {"class":"ARMPITS_EXPOSED","score":0.7133167386054993,"box":[460,196,55,60]},
      {"class":"BELLY_EXPOSED","score":0.6663662195205688,"box":[251,316,156,133]},
      {"class":"FEMALE_BREAST_EXPOSED","score":0.5400498509407043,"box":[226,223,114,100]}
    ],
    [
      {"class":"FACE_FEMALE","score":0.8708316683769226,"box":[203,164,207,226]}
    ]
  ]

Usage: This API returns visual properties detected within an image along with their respective scores. The box parameter indicates the area of the image where a specific property has been detected, enabling you to censor the image as needed. The following properties may be returned if detected:

  • FEMALE_GENITALIA_COVERED
  • FACE_FEMALE
  • BUTTOCKS_EXPOSED
  • FEMALE_BREAST_EXPOSED
  • FEMALE_GENITALIA_EXPOSED
  • MALE_BREAST_EXPOSED
  • ANUS_EXPOSED
  • FEET_EXPOSED
  • BELLY_EXPOSED
  • ARMPITS_EXPOSED
  • FACE_MALE
  • MALE_GENITALIA_EXPOSED

5. Age Verification API

Method: POST

Endpoint: https://api.cloudants.io/age-verify/v1

Note: Ensure the URL does not have a trailing slash and authenticate with either the X-Domain header or an API key (see Authentication above). Unlike the other endpoints, this API takes a single selfie image per request — either an image URL or a file upload — rather than a batch of URLs.

Request Parameters:

Using an Image URL:
{
    "image_url": "https://image-path.com"
  }
Using a File Upload:

Send a multipart/form-data request with the file in the image field instead.

Response Example:

{
    "estimated_age_range": [21, 44],
    "age_bucket": "Adult 21-44",
    "confidence": 0.8306,
    "is_over_18": true,
    "verification_id": "b3a8c1e2-4d9f-4a2b-8e7c-1f0a9d6c5b4e"
  }

Usage: the model classifies the detected face into one of five age bands (age_bucket: Child 0-12, Teenager 13-20, Adult 21-44, Middle Age 45-64, or Aged 65+); estimated_age_range is that band's numeric range. confidence is the model's own certainty in that specific classification. is_over_18 is deliberately conservative — only true for Adult 21-44 and older bands, since Teenager 13-20 straddles the real threshold — treat it as a signal to inform your own policy, not a legal age-verification guarantee. Uploaded images are never retained; only the estimation result is stored, referenced by verification_id.

6. Moderate Listing API

Method: POST

Endpoint: https://api.cloudants.io/moderate-listing/v1

Note: Ensure the URL does not have a trailing slash and authenticate with either the X-Domain header or an API key (see Authentication above). Bundles NSFW, nudity, and image-property detection behind a single allow/flag/block decision per image, driven by a policy. Batches are capped at 10 images (lower than the other endpoints' 25 — this runs three detectors per image).

Request Parameters:

{
    "image_urls": [
      "https://image-path.com"
    ],
    "policy": "general_marketplace"
  }

policy is optional (defaults to general_marketplace) and must be one of:

  • general_marketplace — blocks explicit exposure, flags breast/buttocks exposure (swimwear/fashion photos are common and shouldn't auto-block)
  • dating_profile_photos — same block thresholds, more lenient flag threshold for breast/buttocks exposure
  • classifieds_strict — no flag tier; any exposure above a low threshold is blocked outright
  • custom — reads your own per-category thresholds, set from your dashboard. Returns a 400 if you haven't saved one yet.

Response Example:

{
    "results": [
      {
        "image_url": "https://image-path.com",
        "decision": "flag",
        "reasons": [
          {"category": "FEMALE_BREAST_EXPOSED", "score": 0.61, "action": "flag"}
        ],
        "detections": {
          "is_nsfw": false,
          "is_nude": true,
          "total_nudity_score": 0.61,
          "properties": [
            {"class": "FEMALE_BREAST_EXPOSED", "score": 0.61, "box": [120, 80, 200, 180]}
          ]
        }
      }
    ],
    "overall_decision": "flag"
  }

Usage: decision/overall_decision are one of allow, flag, or block. overall_decision is the worst decision across every image in the batch. reasons lists only the categories that actually triggered your policy — categories not covered by your policy (faces, feet, belly, armpits) are always allowed regardless of score, since they're not explicit content.

Webhooks

If you've set a webhook URL from your dashboard, a listing.flagged event is sent whenever overall_decision is flag or block. Delivery is best-effort — a single attempt with a 5-second timeout, no retries, no delivery log. Each request includes an X-CloudAnts-Signature header: hash_hmac('sha256', $requestBody, $yourWebhookSecret). Verify it before trusting the payload.

7. TakeDown Kit API (TAKE IT DOWN Act)

Re-upload blocking for reported non-consensual intimate images. Requires a TakeDown Kit portal with Pro on your account. Authenticate like every other endpoint (see Authentication). Up to 10 images per request. Images are fingerprinted in memory and never stored — only a SHA-256 hash and a 64-bit perceptual hash are kept.

Add to blocklist: POST https://api.cloudants.io/takedown-block/v1

{
    "image_urls": ["https://cdn.example.com/uploads/abc.jpg"],
    "label": "internal-case-1234"
  }
{
    "results": [
      {"image_url": "https://cdn.example.com/uploads/abc.jpg", "status": "blocked", "hash_id": 42}
    ]
  }

status is blocked, already_blocked, or error (with an error message). Requests received through your hosted portal can be blocked from the dashboard with one click instead.

Check an upload: POST https://api.cloudants.io/takedown-check/v1

Call this before publishing a user upload.

{
    "image_urls": ["https://cdn.example.com/uploads/new.jpg"]
  }
{
    "results": [
      {
        "image_url": "https://cdn.example.com/uploads/new.jpg",
        "match": true,
        "match_type": "perceptual",
        "distance": 4,
        "reference": "TD-7K2Q9XWA"
      }
    ],
    "any_match": true
  }

Usage: match_type is exact (same file) or perceptual (visually the same after resizing or recompression; distance is 0–10, lower = closer). reference is the takedown request (or your API label) the match came from. Perceptual matching does not catch crops, rotations or heavy edits, so keep human review in your process.

Webhook

On Pro, each new portal request sends a takedown.received event (reference, received_at, deadline_at, content_urls, involves_minor, dashboard_url) to the webhook URL set on your dashboard, signed exactly like listing.flagged above.

Required Headers:

  • X-Domain: The domain registered to your account (e.g., example.com) — required unless you're authenticating with an API key instead. See Authentication above.