M
    Mapiok
    Log InSign Up
    API Documentation

    Tools API Tutorial

    Learn how to use the unified Tools API for web scraping, AI image generation, and data extraction.

    Web Scraper
    Extract content from any web page with JavaScript rendering support
    AI Generator
    Generate images from text using AI models like Flux and Stable Diffusion
    All Tools
    Browse the full catalog of available tools and integrations

    Getting Started

    1

    Get your API Key

    Sign in to your account and generate an API key from the API Key page. Keep your key secure and never expose it in client-side code.

    Security tip: Always use environment variables to store your API key. Never commit it to version control.

    2

    Choose a Tool

    Browse the Tools Catalog to find the right tool for your needs. Each tool has a unique slug used in the API endpoint.

    web-scraper
    ai-generator
    instagram-scraper
    + more
    3

    Make API Calls

    All tools use the same pattern: submit a job, then poll for results or receive them via webhook. Choose your preferred language below to see examples.

    API Flow

    1. Submit Job
    POST /tools/{slug}/execute
    2. Get Job ID
    Returns immediately
    3. Poll Status
    GET /tools/jobs/{jobId}
    4. Get Result
    When status = success

    Free Tier

    Start building for free — no credit card required.

    50 Welcome Credits

    New accounts receive 50 credits on signup to explore all tools.

    3 Free Runs / Day

    Run any tool up to 3 times per day even when your credit balance is 0.

    Need more? Purchase a credit package for unlimited access.

    Code Examples

    1. Submit Job

    curl -X POST "https://api.example.com/api/v1/tools/web-scraper/execute" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "input": {
    "url": "https://example.com",
    "javascript": true
  }
}'

    2. Check Status

    curl -X GET "https://api.example.com/api/v1/tools/jobs/{jobId}" \
  -H "Authorization: Bearer YOUR_API_KEY"

    3. Poll Until Done (bash)

    # Replace {jobId} with the actual job ID from step 1
JOB_ID="your-job-id-here"
API_KEY="YOUR_API_KEY"

while true; do
  RESPONSE=$(curl -s "https://api.example.com/api/v1/tools/jobs/$JOB_ID" \
    -H "Authorization: Bearer $API_KEY")
  
  STATUS=$(echo $RESPONSE | grep -o '"status":"[^"]*"' | cut -d'"' -f4)
  echo "Status: $STATUS"
  
  if [ "$STATUS" = "success" ] || [ "$STATUS" = "failed" ]; then
    echo "$RESPONSE" | python3 -m json.tool
    break
  fi
  
  sleep 2
done

    Webhook Delivery

    Instead of polling, you can receive results via webhook. Pass an optional webhookUrl when executing a tool, and Mapiok will POST the result to your URL when the job completes.

    Execute with Webhook

    curl -X POST "https://api.example.com/api/v1/tools/web-scraper/execute" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "input": {
    "url": "https://example.com",
    "javascript": true
  },
  "webhookUrl": "https://your-server.com/webhooks/mapiok"
}'

    Webhook Payload

    {
  "event": "job.completed",
  "jobId": "abc123xyz",
  "toolSlug": "web-scraper",
  "status": "success",
  "result": { "items": [{ "url": "...", "data": { ... } }] },
  "creditsCharged": 1,
  "error": null,
  "errorCode": null,
  "timestamp": "2026-02-14T12:00:00.000Z"
}

    Verify Signature

    Every webhook includes an X-Mapiok-Signature header (HMAC-SHA256). Verify it using the Webhook Signing Secret from your API Key page.

    import { createHmac, timingSafeEqual } from 'crypto';

function verifySignature(rawBody, signatureHeader, secret) {
  const expected = 'sha256=' + createHmac('sha256', secret)
    .update(rawBody).digest('hex');
  return signatureHeader.length === expected.length &&
    timingSafeEqual(Buffer.from(signatureHeader), Buffer.from(expected));
}

// Express.js handler
app.post('/webhooks/mapiok', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-mapiok-signature'];
  if (!verifySignature(req.body, signature, process.env.MAPIOK_WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  const payload = JSON.parse(req.body);
  console.log(payload.event, payload.jobId, payload.result || payload.error);
  res.status(200).send('OK');
});

    Retry policy: If your endpoint is unreachable or returns a non-2xx status, Mapiok retries up to 3 times with exponential backoff (5s, 30s, 120s). The webhook URL must be HTTPS. Your endpoint must respond within 10 seconds.

    Response Examples

    Job Created Response
    {
  "data": {
    "jobId": "abc123xyz",
    "status": "pending",
    "estimatedCredits": 1
  }
}
    Job Completed Response
    {
  "data": {
    "status": "success",
    "creditsUsed": 1,
    "result": {
      "items": [
        {
          "url": "https://example.com",
          "html": "<!DOCTYPE html>...",
          "data": { "title": "Example" }
        }
      ]
    }
  }
}
    Job Failed Response
    {
  "data": {
    "status": "failed",
    "error": "Target URL returned 403 Forbidden"
  }
}
    Error Response (e.g. 402)
    {
  "error": "Insufficient credits",
  "details": {
    "required": 1,
    "available": 0
  }
}

    Best Practices

    Do
    • • Use webhooks instead of polling for server-to-server flows
    • • Verify webhook signatures before processing
    • • Use exponential backoff when polling
    • • Handle rate limit errors (429) gracefully
    • • Store API keys in environment variables
    • • Check credits balance before bulk operations
    Don't
    • • Expose API keys in client-side code
    • • Poll too frequently (respect rate limits)
    • • Ignore error responses
    • • Hardcode API keys in source code
    • • Make synchronous blocking calls

    Ready to get started?