The GearTrain API exposes account resources to personal access tokens.
Base URL#
Production: https://app.geartrain.dev/api/v1
Local development: http://localhost:3000/api/v1
All operation paths in this document are relative to that base URL.
Authentication#
Send a token from Settings > API Tokens as a bearer credential:
Authorization: Bearer gt_pat_...
Each token carries explicit scopes. Operations document their required
scope with x-required-scope. A missing or invalid token returns 401;
a valid token without the required scope returns 403. Authentication is
checked before the request body is parsed.
A 401 includes WWW-Authenticate: Bearer realm="api". A scope failure
adds the missing scope, for example:
WWW-Authenticate: Bearer realm="api", error="insufficient_scope", scope="jobs:write"
Quickstart#
Create a job, queue a run, and read it back:
curl -X POST "https://app.geartrain.dev/api/v1/jobs" \
-H "Authorization: Bearer $GEARTRAIN_API_TOKEN" \
-H "Content-Type: application/json" \
--data '{"name":"Nightly sync","cron":"0 2 * * *","scriptPath":"/sync.js"}'
Response (abridged):
{"ok":true,"requestId":"req_...","data":{"job":{"id":42,"name":"Nightly sync","cron":"0 2 * * *","scriptPath":"/sync.js","status":"active"}}}
Queue a manual run:
curl -X POST "https://app.geartrain.dev/api/v1/jobs/42/runs" \
-H "Authorization: Bearer $GEARTRAIN_API_TOKEN" \
-H "Idempotency-Key: run-2026-11-05"
{"ok":true,"requestId":"req_...","data":{"runId":"3f0a6f9e-5b2c-4c1d-9e8f-7a6b5c4d3e2f"}}
Read the run back. An accepted run is immediately visible as queued:
curl "https://app.geartrain.dev/api/v1/runs/3f0a6f9e-5b2c-4c1d-9e8f-7a6b5c4d3e2f" \
-H "Authorization: Bearer $GEARTRAIN_API_TOKEN"
{"ok":true,"requestId":"req_...","data":{"run":{"runId":"3f0a6f9e-5b2c-4c1d-9e8f-7a6b5c4d3e2f","jobId":null,"jobName":null,"status":"queued","attemptCount":0,"attempts":[]}}}
A validation failure looks like:
{"ok":false,"requestId":"req_...","error":{"code":"validation","message":"cron is required.","field":"cron"}}
Check plan usage:
curl "https://app.geartrain.dev/api/v1/account/usage" \
-H "Authorization: Bearer $GEARTRAIN_API_TOKEN"
{"ok":true,"requestId":"req_...","data":{"usage":{"plan":"free","jobs":{"used":3,"limit":5},"runs":{"used":120,"limit":5000,"period":"2026-11","resetsAt":"2026-12-01T00:00:00.000Z"},"storage":{"usedBytes":1048576,"limitBytes":26214400,"filesBytes":700000,"logsBytes":200000,"systemBytes":148576}}}}
Responses#
Successful responses use:
{
"ok": true,
"requestId": "req_...",
"data": {}
}
Failures use:
{
"ok": false,
"requestId": "req_...",
"error": {
"code": "validation",
"message": "Human-readable description."
}
}
error.code is the stable machine-readable contract. error.message is
safe to display. error.field names the offending request field when one
applies.
A known path called with an unsupported method returns 405 with an
Allow header. Responses carry Cache-Control: no-store and no ETag.
Error codes#
error.code is the stable machine-readable contract. error.field names
the offending request field when one applies.
| Status |
Code |
Meaning |
Retry |
Field |
| 400 |
validation |
Malformed body, query, or field. |
No |
Yes |
| 400 |
invalid_path |
File path is not absolute or is malformed. |
No |
path |
| 400 |
root_protected |
The root directory cannot be deleted. |
No |
|
| 400 |
folder_download |
Folders cannot be downloaded. |
No |
path |
| 400 |
no_file |
Upload request carried no file part. |
No |
file |
| 400 |
schedule_interval |
Cron runs more often than the plan allows. |
No |
cron |
| 400 |
invalid_run_env |
Run environment is malformed. |
No |
env |
| 400 |
invalid_secret |
Webhook signing secret is missing or does not match the source’s required format. |
No |
secret |
| 400 |
limit_reached |
Job already has the maximum number of active webhook endpoints. |
No |
endpoints |
| 401 |
unauthorized |
Missing or malformed bearer token. |
No |
|
| 401 |
invalid_token |
Token is unknown. |
No |
|
| 401 |
expired_token |
Token has expired. |
No |
|
| 401 |
revoked_token |
Token has been revoked. |
No |
|
| 403 |
insufficient_scope |
Token lacks the required scope. |
No |
|
| 403 |
job_limit |
Active-job limit reached. |
No |
|
| 403 |
run_limit |
Monthly run limit reached. |
No |
|
| 403/413 |
quota_exceeded |
Storage limit reached (jobs return 403, files 413). |
No |
|
| 404 |
not_found |
Generic resource not found. |
No |
|
| 404 |
job_not_found |
Job is missing, deleted, or owned by another user. |
No |
|
| 404 |
run_not_found |
Run is missing, deleted, or owned by another user. |
No |
|
| 405 |
method_not_allowed |
Method is not supported on this path. |
No |
|
| 409 |
already_exists |
File or folder already exists. |
No |
|
| 409 |
file_exists |
Script path already exists. |
No |
scriptPath |
| 409 |
idempotency_conflict |
Idempotency key reused with different input. |
No |
|
| 409 |
idempotency_in_progress |
First request for this key is still running. |
Yes, later |
|
| 409 |
run_already_started |
Run has started and cannot be cancelled. |
No |
|
| 413 |
payload_too_large |
JSON body exceeds the 1 MiB request limit. |
No |
|
| 413 |
too_large |
File content exceeds the 10 MiB read limit. |
No |
path |
| 429 |
rate_limited |
Plan request rate exceeded. |
Yes, after Retry-After |
|
| 500 |
internal_error |
Unexpected server error. |
Yes, with an idempotency key for mutations |
|
| 500 |
create_failed |
Unexpected failure creating a file. |
Yes, with an idempotency key |
|
| 500 |
schedule_failed |
Unexpected failure scheduling a job. |
Yes, with an idempotency key |
|
| 500 |
save_failed |
Unexpected failure saving a file. |
Yes, with an idempotency key |
|
| 500 |
delete_failed |
Unexpected failure deleting a resource. |
Yes, with an idempotency key |
|
| 500 |
rename_failed |
Unexpected failure renaming a file. |
Yes, with an idempotency key |
|
| 500 |
upload_failed |
Unexpected failure uploading a file. |
Yes, with an idempotency key |
|
| 500 |
download_failed |
Unexpected failure streaming a file. |
Yes |
|
| 500 |
list_failed |
Unexpected failure listing a directory. |
Yes |
|
| 500 |
read_failed |
Unexpected failure reading a file. |
Yes |
|
| 500 |
vault_unavailable |
Secret storage is unavailable. |
Yes, later |
|
| 500 |
enqueue_failed |
Could not queue a run. |
Yes |
|
Inbound webhook deliveries (POST /hooks/{endpointId}) use their own
response codes, documented under
Webhooks → Responses and Retries.
Request IDs#
Every response includes X-Request-Id. The same value appears in the
response body when a body is returned. Include it when contacting support.
Rate limits#
Requests are limited per user, across all of that user’s tokens:
| Plan |
Limit |
| Free |
60 requests/minute |
| Pro |
600 requests/minute |
A rate-limited request returns 429 with Retry-After and the standard
RateLimit headers, for example:
Retry-After: 42
RateLimit: "60-in-1min"; r=0; t=42
Manual runs (POST /jobs/{jobId}/runs) are exempt from the plan’s
concurrent-run cap. They are limited to 5 per minute and 100 per day per
user, and they count toward the monthly run quota.
Plan limits#
| Limit |
Free |
Pro |
API behavior |
| Active jobs |
5 |
50 |
403 job_limit |
| Minimum schedule interval |
15 minutes |
1 minute |
400 schedule_interval |
| Runs per month |
5,000 |
50,000 |
403 run_limit |
| Concurrent scheduled runs |
1 |
5 |
Extra runs wait; not an error |
| Storage |
25 MB |
1 GB |
403/413 quota_exceeded |
| Log retention |
3 days |
30 days |
Older events and logs are deleted |
| API requests |
60/minute |
600/minute |
429 rate_limited |
Paused and soft-deleted jobs do not count toward the active-job limit.
Manual runs are exempt from the concurrent-run limit and are limited to
5 per minute and 100 per day. Use GET /account/usage to check current
consumption against these limits.
Cron schedules#
Cron expressions are evaluated in the account’s timezone (see
GET /account). Five-field expressions
(minute hour day-of-month month day-of-week) are the common form;
six-field expressions with a leading seconds field are also accepted.
The plan’s minimum schedule interval applies to the effective interval.
On Free, */15 * * * * is allowed, while */14 * * * * returns
400 schedule_interval.
The run list endpoints (GET /runs) use opaque cursors. Pass limit and
cursor, then use data.pagination.nextCursor for the next page. Do not
construct cursors yourself. GET /jobs returns all of the user’s jobs and
has no pagination parameters.
File paths#
File system paths are absolute and URL-encoded. Read and delete operations
pass the path as a query parameter; file writes pass it in the JSON body.
Paths must start with /, must not contain empty, . or .. segments,
must not contain null bytes, and are limited to 1024 characters.
Query strings can appear in access logs and browser history. Avoid placing
sensitive file names in paths where possible, and never log the path
query parameter unredacted.
File sizes#
JSON request bodies are capped at 1 MiB (1,048,576 bytes). The cap
applies to the entire body, so the content string in
PUT /files/content must be smaller than 1 MiB because of the JSON
overhead. GET /files/content returns content up to 10 MiB
(10,485,760 bytes); use GET /files/download for larger files. Uploads
are bounded by the plan’s remaining storage.
Idempotency#
Side-effecting POST operations accept an optional Idempotency-Key.
Reusing a key with the same request replays the original response. Reusing
it with a different request returns 409. A replay includes
Idempotency-Replayed: true and the original requestId.
Soft-deleted jobs#
DELETE /jobs/{jobId} marks a job deleted and removes its schedule. The
job is hidden from the default job list but remains visible with
GET /jobs?status=deleted. Deleted jobs do not count toward the
active-job limit. Their run history is retained and can still be queried
with GET /runs?jobId={jobId}. There is no purge endpoint.
Browser access#
This API is intended for server-side clients and agents. It does not send
CORS headers, so browsers cannot call it cross-origin; route browser
requests through a same-origin backend instead. Never embed a
gt_pat_... token in browser code, where any script on the page could
read it.
All operations in this document are implemented. The v1 contract is
stable; breaking changes are announced in the changelog.