API Endpoint

Reference for the Humanmark API endpoint.

POST

Create Challenge


/api/v1/challenge/create

Creates a new Humanmark challenge.

Request Body

Parameter	Type	Required	Description
domain	string	Yes	Your domain (must be allowlisted with Humanmark)

Example Request

create-challenge.sh

curl -X POST https://humanmark.io/api/v1/challenge/create \
  -H "hm-api-key: YOUR_API_KEY" \
  -H "hm-api-secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "yourdomain.com",
  }'

Example Response

response.json

{
  "token": "<TOKEN>",
  "challenge": "<CHALLENGE>"
}

Response Codes

200 Success

Challenge created successfully

Returns: token and challenge

All error responses follow this format:

error-response.json

{
  "message": "Domain not registered to your account",
  "code": "INVALID_DOMAIN"
}

401 Unauthorized

Invalid API key or secret

Code: UNAUTHORIZED

429 Too Many Requests

Rate limit exceeded

Code: RATE_LIMIT_EXCEEDED

403 Forbidden

Domain not registered to your account

Code: INVALID_DOMAIN

5xx Server Error

Internal server error - please contact support

Code: INTERNAL

Code Examples

Python

humanmark.py

# Using requests
import requests
import os

def create_humanmark_challenge():
    response = requests.post(
        'https://humanmark.io/api/v1/challenge/create',
        headers={
            'Content-Type': 'application/json',
            'hm-api-key': os.environ['HUMANMARK_API_KEY'],
            'hm-api-secret': os.environ['HUMANMARK_API_SECRET']
        },
        json={'domain': 'yourdomain.com'}
    )
    
    return response.json()

JavaScript / Node.js

humanmark.js

// Using fetch
const createChallenge = async () => {
  const response = await fetch('https://humanmark.io/api/v1/challenge/create', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'hm-api-key': process.env.HUMANMARK_API_KEY,
      'hm-api-secret': process.env.HUMANMARK_API_SECRET
    },
    body: JSON.stringify({
      domain: 'yourdomain.com'
    })
  });
  
  const data = await response.json();
  return data;
};