Getting started
Connect to Motor
The API base URL is https://api.motor.dev. Use your team’s secret key. If your team doesn’t have an account or key, someone must sign up, then create a secret key on the API keys page. Keep the key on your backend. Check its service access with:
curl https://api.motor.dev/key \
-H "Authorization: Bearer $MOTOR_KEY"HTTP 200
{
"id": "key_...",
"name": "Application",
"kind": "secret",
"apis": "all",
"spent_cents": 0,
"limit_cents": 1000
}Responses in these guides are trimmed. Replace sample IDs, secrets, checksums, ETags, and times with actual values. Requests can incur charges; read the service’s pricing and test-mode rules before running them.
Shared conventions
- Authentication: use the credential specified for each endpoint. Some calls use a ping URL or a scoped client token instead of a secret key.
- Idempotency and retries: save a key for each logical write, then reuse it for the same request after a lost response. Requirements and replay windows vary by endpoint.
- Errors: handle errors by status and code. Fix validation failures before retrying.
- Pagination: use next_cursor to fetch the next page with the same filters. Results appear in data or items, depending on the service.
- IDs and times: preserve returned IDs and use RFC 3339 timestamps; do not infer state from an ID.
Choose a service
| Service | When to use it |
|---|---|
| Artifact storage | Keep private files with metadata and prepaid retention, then issue short-lived download URLs. |
| Audit logs | Record decisions and outcomes in an append-only ledger with independently verifiable checkpoints. |
| Job monitors | Detect missing check-ins, failures, and overruns in jobs that your own scheduler runs. |
| Phone numbers | Search, buy, label, and release US numbers. Motor cannot send or receive texts or calls yet. |
| Prompt flags | Compare prompt versions using outcomes reported by your application. |
| Scheduled jobs | Run work later, retry failures, or limit the rate of provider calls. |
| Webhooks | Send events to customers or receive verified provider events by HTTP or polling. |
Scheduling, monitoring, or webhooks?
- Run something later or on a schedule → Scheduled jobs.
- Find out when a job running elsewhere stops checking in → Job monitors.
- Notify another server, or receive events from one → Webhooks.
Limits to check
- Scheduled jobs: delays and deadlines are limited to 7 days; jobs may arrive more than once.
- Job monitors: prune_tag deletes omitted monitors; monitors keep accruing charges after a key reaches its limit.
- Webhooks: receivers must verify and deduplicate; replay adds delivery charges.
- Prompt flags: use a safe default when evaluation fails; disabling does not stop in-flight work.
- Audit logs: receipts prove recorded bytes, not the truth of claims; prepaid retention does not renew automatically.
- Artifact storage: download URLs last at most 300 seconds; uploads require checksums, and unpaid artifacts are deleted after 30 days.
- Phone numbers: there are no texts or calls yet; renewals can exceed a key’s spending limit.
Next steps
Choose a task from your service’s Examples section. Its API reference and OpenAPI specification describe request and response fields; the guide covers limits and pricing.
Platform docs cover client tokens, Motor events, and usage. Motor events report changes to your Motor resources; Webhooks can receive events from other providers.