API Reference

Overview

BitMind provides multiple API endpoints for different use cases, from consumer applications to enterprise-grade services. This document provides an overview of available APIs with complete OpenAPI specifications for detailed implementation.

📋 OpenAPI Specifications

Complete OpenAPI 3.0 specifications are available for all APIs:

• Subnet API - AI content detection services (Oracle API)

• Enterprise API - Enterprise-grade services

View and interact with these specifications using Swagger UI or generate client SDKs using OpenAPI Generator.

API Categories

1. Subnet API (Oracle API)

• Base URL: https://api.bitmind.ai/oracle/v1

• Purpose: AI content detection services

• Authentication: Bearer token (API key or JWT)

• Rate Limits: API key users (based on subscription tier), JWT users (1 req/sec with burst)

2. Enterprise API

• Base URL: https://enterprise.bitmind.ai

• Purpose: Enterprise-grade detection services

• Authentication: API key + OAuth 2.0

• Rate Limits: 1,000-10,000+ requests/hour

API Overview

Subnet API (Oracle API)

The Subnet API provides AI content detection services with comprehensive image and video analysis capabilities. Key features include:

• Image Detection: Multi-version processing with C2PA analysis

• Video Detection: Frame-by-frame analysis with preprocessing

• Video Preprocessing: Browser-compatible conversion and thumbnail generation

• Upload Management: Presigned S3 URLs for large file uploads

For complete endpoint documentation, see the Subnet API OpenAPI Specification.

Enterprise API

The Enterprise API provides high-performance, enterprise-grade detection services with advanced features:

• Health Monitoring: Service status and health checks

• Image Inference: Binary and JSON-based image processing

• Video Inference: Enterprise-grade video analysis

• Batch Processing: Efficient multi-file processing

• Privacy-Compliant: See Compliance & Privacy for details

For complete endpoint documentation, see the Enterprise API OpenAPI Specification.

Error Handling

Standard Error Response

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Missing required field: image",
    "details": {
      "field": "image",
      "expected_type": "binary_data"
    },
    "request_id": "req_1234567890",
    "timestamp": "2024-01-01T00:00:00Z"
  }
}

Common Error Codes

Code	Description	HTTP Status
INVALID_REQUEST	Malformed request	400
UNAUTHORIZED	Invalid authentication	401
FORBIDDEN	Insufficient permissions	403
NOT_FOUND	Resource not found	404
RATE_LIMITED	Rate limit exceeded	429
INTERNAL_ERROR	Server error	500
SERVICE_UNAVAILABLE	Service temporarily unavailable	503

Rate Limits

Subnet API (Oracle API)

• API Key users: Rate limits based on subscription tier

• JWT users: 1 request per second with burst allowance of 5 requests

• Application-specific: Rate limits may vary based on the x-bitmind-application header

Enterprise API

• Standard: 1,000 requests/hour

• Enterprise: 10,000+ requests/hour

• Custom: Negotiable for large deployments

cURL Examples

Oracle API - Image Detection

curl -X POST \
  -H "Authorization: Bearer your-api-key" \
  -H "x-bitmind-application: oracle-api" \
  -H "Content-Type: application/json" \
  -d '{"image": "https://example.com/image.jpg", "rich": true}' \
  "https://api.bitmind.ai/oracle/v1/34/detect-image"

Oracle API - Video Detection

curl -X POST \
  -H "Authorization: Bearer your-api-key" \
  -H "x-bitmind-application: oracle-api" \
  -H "Content-Type: multipart/form-data" \
  -F "[email protected]" \
  -F "rich=true" \
  "https://api.bitmind.ai/oracle/v1/34/detect-video"

Enterprise Batch Processing

curl -X POST \
  -H "Authorization: Bearer bm-enterprise-company-001" \
  -H "Content-Type: multipart/form-data" \
  -F "[email protected]" \
  -F "[email protected]" \
  -F "[email protected]" \
  "https://enterprise.bitmind.ai/batch_image"

Large File Upload Workflow

The Subnet API has a 10MB limit for direct file uploads due to API Gateway restrictions. For larger files (up to 200MB), use the following workflow with presigned S3 URLs:

Overview

This three-step process allows you to upload large video files:

1. Request a presigned S3 URL

2. Upload your file directly to S3

3. Process the video using the S3 URL

Step 1: Request Presigned Upload URL

Get a presigned S3 URL and credentials for uploading your file:

curl -X POST "https://api.bitmind.ai/oracle/v1/34/get-video-upload-url" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "video.mp4",
    "contentType": "video/mp4"
  }'

Response:

{
  "url": "https://applications-temp-videos-us-east-1.s3.us-east-1.amazonaws.com/",
  "fields": {
    "key": "temp/video-uuid.mp4",
    "Content-Type": "video/mp4",
    "bucket": "applications-temp-videos-us-east-1",
    "X-Amz-Algorithm": "AWS4-HMAC-SHA256",
    "X-Amz-Credential": "...",
    "X-Amz-Date": "...",
    "X-Amz-Security-Token": "...",
    "Policy": "...",
    "X-Amz-Signature": "..."
  },
  "videoUrl": "https://applications-temp-videos-us-east-1.s3.us-east-1.amazonaws.com/temp/video-uuid.mp4"
}

Step 2: Upload to S3

Upload your file using the presigned URL and credentials from Step 1:

curl -X POST "YOUR_S3_URL" \
  -F "key=YOUR_S3_KEY" \
  -F "Content-Type=video/mp4" \
  -F "bucket=applications-temp-videos-us-east-1" \
  -F "X-Amz-Algorithm=AWS4-HMAC-SHA256" \
  -F "X-Amz-Credential=YOUR_CREDENTIAL" \
  -F "X-Amz-Date=YOUR_DATE" \
  -F "X-Amz-Security-Token=YOUR_TOKEN" \
  -F "Policy=YOUR_POLICY" \
  -F "X-Amz-Signature=YOUR_SIGNATURE" \
  -F "[email protected]"

Step 3: Process Video

Once uploaded, use the videoUrl from Step 1 to process your video:

curl -X POST "https://api.bitmind.ai/oracle/v1/34/detect-video" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video": "YOUR_VIDEO_URL",
    "rich": true,
    "startTime": 0,
    "endTime": 30,
    "fps": 30
  }'

Complete Bash Script Example

Click to expand complete bash script

#!/bin/bash

# Step 0: Set Configuration
YOUR_API_KEY="your_bitmind_api_key"
VIDEO_FILE="path_to_video.mp4"

# Display configuration for verification
echo "=== Configuration ==="
echo "API Key: $YOUR_API_KEY"
echo "Video File: $VIDEO_FILE"
echo ""

# Step 1: Get presigned URL and store response
echo "=== Step 1: Requesting presigned URL ==="
S3_RESPONSE=$(curl -s -X POST "https://api.bitmind.ai/oracle/v1/34/get-video-upload-url" \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "'$(basename $VIDEO_FILE)'",
    "contentType": "video/mp4"
  }')

echo "S3 Response: $S3_RESPONSE"
echo ""

# Step 1.5: Extract variables from response
echo "=== Step 1.5: Extracting credentials ==="
S3_KEY=$(echo $S3_RESPONSE | jq -r '.fields.key')
S3_CREDENTIAL=$(echo $S3_RESPONSE | jq -r '.fields."X-Amz-Credential"')
S3_DATE=$(echo $S3_RESPONSE | jq -r '.fields."X-Amz-Date"')
S3_TOKEN=$(echo $S3_RESPONSE | jq -r '.fields."X-Amz-Security-Token"')
S3_POLICY=$(echo $S3_RESPONSE | jq -r '.fields.Policy')
S3_SIGNATURE=$(echo $S3_RESPONSE | jq -r '.fields."X-Amz-Signature"')
S3_URL=$(echo $S3_RESPONSE | jq -r '.url')
VIDEO_URL=$(echo $S3_RESPONSE | jq -r '.videoUrl')

# Display extracted variables for verification
echo "S3 Key: $S3_KEY"
echo "S3 URL: $S3_URL"
echo "Video URL: $VIDEO_URL"
echo ""

# Step 2: Upload to S3
echo "=== Step 2: Uploading video to S3 ==="
curl -X POST "$S3_URL" \
  -F "key=$S3_KEY" \
  -F "Content-Type=video/mp4" \
  -F "bucket=applications-temp-videos-us-east-1" \
  -F "X-Amz-Algorithm=AWS4-HMAC-SHA256" \
  -F "X-Amz-Credential=$S3_CREDENTIAL" \
  -F "X-Amz-Date=$S3_DATE" \
  -F "X-Amz-Security-Token=$S3_TOKEN" \
  -F "Policy=$S3_POLICY" \
  -F "X-Amz-Signature=$S3_SIGNATURE" \
  -F "file=@$VIDEO_FILE"

echo ""
echo "Upload complete!"
echo ""

# Step 3: Process video
echo "=== Step 3: Processing video ==="
curl -X POST "https://api.bitmind.ai/oracle/v1/34/detect-video" \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video": "'$VIDEO_URL'",
    "rich": true,
    "startTime": 0,
    "endTime": 30,
    "fps": 30
  }'

Important Notes

• File Size Limit: Maximum file size is 200MB (compared to 10MB for direct uploads)

• Presigned URL Expiry: URLs expire in 15 minutes - complete all steps within this timeframe

• Supported Formats: mp4, mov, avi, mkv, webm, wmv

• Requirements: You'll need jq installed for JSON parsing in the bash script

• File Location: Ensure your video file exists at the specified path

When to Use This Workflow

Use this workflow when:

• Your video file exceeds 10MB

• You need to upload files up to 200MB

• You want more reliable uploads for large files

• You're implementing a production application with large media files

For files under 10MB, you can use the direct upload method shown in the cURL examples above.

Best Practices

1. Authentication

• Store API keys securely (environment variables, key management systems)

• Never commit API keys to version control

• Use different keys for different environments

• Rotate keys regularly

2. Error Handling

• Always check response status codes

• Implement exponential backoff for retries

• Log errors for debugging

• Handle rate limits gracefully

3. Performance

• Use batch endpoints for multiple files

• Implement caching for repeated requests

• Monitor API usage and limits

• Use appropriate timeouts

4. Security

• Validate input data before sending

• Use HTTPS for all requests

• Implement request signing where required

• Monitor for suspicious activity

Resources

• OpenAPI Specifications: See links above

• For help, visit the Support page

---

For the most up-to-date API documentation, visit docs.bitmind.ai