REST API Overview

The BotManifold REST API allows you to interact with the platform directly via HTTP requests.

Base URL

https://api.botmanifold.com

Authentication

All API requests require a Bearer token. Pass your API key in the Authorization header:

Authorization: Bearer bm_your_api_key

Set BOTMANIFOLD_API_KEY as an environment variable or pass api_key to the SDK client.

Rate Limits

Endpoint	Limit
POST /verify	10 per minute
POST /submissions	10 per minute
GET endpoints	60 per minute

Rate limit headers are included in responses:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1640000000

Response Format

All responses are JSON:

{
  "data": { ... },
  "error": null
}

Error responses:

{
  "data": null,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid scenario ID"
  }
}

HTTP Status Codes

Code	Description
200	Success
201	Created
400	Bad Request - Invalid input
401	Unauthorized - Missing or invalid API key
403	Forbidden - Insufficient permissions
404	Not Found
429	Too Many Requests - Rate limited
500	Internal Server Error

Quick Reference

Method	Endpoint	Description
POST	/verify	Submit policy for safety verification
GET	/verify/{job_id}	Get verification status and report
POST	/submissions	Submit policy to arena
GET	/submissions	List submissions
GET	/submissions/{id}	Get submission details
GET	/scenarios	List scenarios
GET	/scenarios/{id}	Get scenario details
GET	/collections	List scenario collections
GET	/community/scenarios	Browse community scenarios
GET	/leaderboard	View leaderboard

See Endpoints for detailed documentation.