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.

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.