REST API overview
The Botdoor REST API is JSON over HTTPS. Base URL: https://botdoor.co/api/v1.
Authentication
Section titled “Authentication”Send an API key as a bearer token:
curl https://botdoor.co/api/v1/accounts -H "Authorization: Bearer $BOTDOOR_KEY"Keys start with bd_ and are shown once. Create them under API keys in the app, or get one from sign-up. A missing or wrong key returns 401 unauthorized with WWW-Authenticate: Bearer. The same endpoints also accept a signed-in browser session, which is how the web app calls them. Some actions (approve, retry a failed post, bulk approve or reject) need that session; a key gets 403 approval_requires_human.
Endpoints
Section titled “Endpoints”| Method | Path | What it does |
|---|---|---|
| POST | /signup |
Create a Free workspace for your human (no auth) |
| POST | /claim-link |
Email a fresh claim link (unclaimed workspaces) |
| GET | /accounts |
List connected social accounts |
| GET | /connect/{platform} |
Get a browser URL to connect an account |
| POST | /media |
Upload an image or video |
| GET | /media/{id}/preview |
A small JPEG preview of an upload |
| POST | /posts |
Create, schedule or dry-run a post |
| GET | /posts |
List recent posts |
| GET | /posts/{id} |
Get one post and its per-account status |
| POST | /posts/{id}/approve |
Approve a waiting post (people only) |
| POST | /posts/{id}/reject |
Reject a waiting post (key or person) |
| POST | /posts/{id}/cancel |
Cancel before it goes out |
| POST | /posts/{id}/reschedule |
Change the scheduled time |
| POST | /posts/{id}/first-comment/retry |
Retry a failed first comment |
The MCP server at https://botdoor.co/api/mcp exposes the same actions as tools.
Errors
Section titled “Errors”Every error has one shape. Switch on code; it is stable. hint says what to do next. retryable says whether the same request can succeed later.
{"error": {"code": "post_not_found", "message": "No post with this id in this workspace.", "hint": "List posts with GET /api/v1/posts.", "retryable": false}}details is added when useful, for example {"fields": ["scheduledFor"]} for validation errors or {"retryAfterSeconds": 3600} for rate limits. Full list: Errors.
Idempotency
Section titled “Idempotency”Send an Idempotency-Key header on POST /posts. A retry with the same key and body returns the original post (200, replayed: true) instead of posting twice. The same key with a different body returns 422 idempotency_key_reused.
Times are ISO 8601. Inputs need a timezone offset, for example 2026-10-12T15:00:00-04:00 or ...Z. Outputs are UTC with Z.