GearTrain REST API

Version 1.0.0 · Authenticated REST API for jobs, webhook endpoints, runs, files, and secrets.

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.

Pagination#

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.

Servers

URL Description
https://app.geartrain.dev/api/v1 Production
http://localhost:3000/api/v1 Local development

Authentication

bearerAuth

Type: http · Scheme: bearer · Format: gt_pat

Personal access token created in Settings > API Tokens.

Account

Token context, account profile, and plan usage.

GET /me

Get the current token context

Returns the user and token identity derived from the bearer token.

Responses

Status Description Schema
200 Current token context.
Headers
  • X-Request-Id string Unique request identifier.
  • RateLimit string Current rate-limit state.
  • RateLimit-Policy string Rate-limit policy for the current plan.
application/json MeResponse
401 Missing, invalid, expired, or revoked bearer token.
Headers
  • X-Request-Id string Unique request identifier.
  • WWW-Authenticate string Bearer challenge describing the authentication failure.
application/json ErrorResponse
403 The token does not grant the required scope or plan quota.
Headers
  • X-Request-Id string Unique request identifier.
  • WWW-Authenticate string Bearer challenge describing the authentication failure.
application/json ErrorResponse
429 The plan rate limit was exceeded.
Headers
  • X-Request-Id string Unique request identifier.
  • Retry-After integer Seconds to wait before retrying.
  • RateLimit string Current rate-limit state.
  • RateLimit-Policy string Rate-limit policy for the current plan.
application/json ErrorResponse
500 An unexpected server error occurred.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
cURL example
curl -X GET "https://app.geartrain.dev/api/v1/me" \
  -H "Authorization: Bearer $GEARTRAIN_API_TOKEN"
GET /account account:read

Get account profile and preferences

Requires the account:read scope.

Responses

Status Description Schema
200 Account profile.
Headers
  • X-Request-Id string Unique request identifier.
  • RateLimit string Current rate-limit state.
  • RateLimit-Policy string Rate-limit policy for the current plan.
application/json AccountResponse
401 Missing, invalid, expired, or revoked bearer token.
Headers
  • X-Request-Id string Unique request identifier.
  • WWW-Authenticate string Bearer challenge describing the authentication failure.
application/json ErrorResponse
403 The token does not grant the required scope or plan quota.
Headers
  • X-Request-Id string Unique request identifier.
  • WWW-Authenticate string Bearer challenge describing the authentication failure.
application/json ErrorResponse
429 The plan rate limit was exceeded.
Headers
  • X-Request-Id string Unique request identifier.
  • Retry-After integer Seconds to wait before retrying.
  • RateLimit string Current rate-limit state.
  • RateLimit-Policy string Rate-limit policy for the current plan.
application/json ErrorResponse
500 An unexpected server error occurred.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
cURL example
curl -X GET "https://app.geartrain.dev/api/v1/account" \
  -H "Authorization: Bearer $GEARTRAIN_API_TOKEN"
GET /account/usage account:read

Get plan usage

Requires the account:read scope. Reports current consumption against the account’s plan limits. Runs are counted per UTC calendar month; storage uses the same measured content basis as enforcement.

Responses

Status Description Schema
200 Quota usage.
Headers
  • X-Request-Id string Unique request identifier.
  • RateLimit string Current rate-limit state.
  • RateLimit-Policy string Rate-limit policy for the current plan.
application/json AccountUsageResponse
401 Missing, invalid, expired, or revoked bearer token.
Headers
  • X-Request-Id string Unique request identifier.
  • WWW-Authenticate string Bearer challenge describing the authentication failure.
application/json ErrorResponse
403 The token does not grant the required scope or plan quota.
Headers
  • X-Request-Id string Unique request identifier.
  • WWW-Authenticate string Bearer challenge describing the authentication failure.
application/json ErrorResponse
429 The plan rate limit was exceeded.
Headers
  • X-Request-Id string Unique request identifier.
  • Retry-After integer Seconds to wait before retrying.
  • RateLimit string Current rate-limit state.
  • RateLimit-Policy string Rate-limit policy for the current plan.
application/json ErrorResponse
500 An unexpected server error occurred.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
cURL example
curl -X GET "https://app.geartrain.dev/api/v1/account/usage" \
  -H "Authorization: Bearer $GEARTRAIN_API_TOKEN"

Jobs

Scheduled and webhook-triggered scripts and manual runs.

GET /jobs jobs:read

List jobs

Requires the jobs:read scope.

Parameters

Name In Type Description
status query string Restrict to one job status. Include `deleted` to list soft-deleted jobs. Allowed: active, paused, deleted

Responses

Status Description Schema
200 Jobs belonging to the user.
Headers
  • X-Request-Id string Unique request identifier.
  • RateLimit string Current rate-limit state.
  • RateLimit-Policy string Rate-limit policy for the current plan.
application/json JobListResponse
401 Missing, invalid, expired, or revoked bearer token.
Headers
  • X-Request-Id string Unique request identifier.
  • WWW-Authenticate string Bearer challenge describing the authentication failure.
application/json ErrorResponse
403 The token does not grant the required scope or plan quota.
Headers
  • X-Request-Id string Unique request identifier.
  • WWW-Authenticate string Bearer challenge describing the authentication failure.
application/json ErrorResponse
429 The plan rate limit was exceeded.
Headers
  • X-Request-Id string Unique request identifier.
  • Retry-After integer Seconds to wait before retrying.
  • RateLimit string Current rate-limit state.
  • RateLimit-Policy string Rate-limit policy for the current plan.
application/json ErrorResponse
500 An unexpected server error occurred.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
cURL example
curl -X GET "https://app.geartrain.dev/api/v1/jobs" \
  -H "Authorization: Bearer $GEARTRAIN_API_TOKEN"
POST /jobs jobs:write

Create a job

Requires the jobs:write scope. The script path must already exist and point to a file, not a directory, unless createScript is true. With createScript, a missing script and its missing parent directories are created. A malformed cron expression returns 400 with code validation and field cron.

Parameters

Name In Type Description
Idempotency-Key header string Optional key for safe retries. Reusing the key with the same request replays the original response.

Request body Required

Content type Schema
application/json CreateJobRequest

Responses

Status Description Schema
201 Job created.
Headers
  • X-Request-Id string Unique request identifier.
  • Idempotency-Replayed boolean Present and true when a stored idempotent response was replayed.
  • RateLimit string Current rate-limit state.
  • RateLimit-Policy string Rate-limit policy for the current plan.
application/json JobResponse
400 The request is missing or invalid.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
401 Missing, invalid, expired, or revoked bearer token.
Headers
  • X-Request-Id string Unique request identifier.
  • WWW-Authenticate string Bearer challenge describing the authentication failure.
application/json ErrorResponse
403 The token does not grant the required scope or plan quota.
Headers
  • X-Request-Id string Unique request identifier.
  • WWW-Authenticate string Bearer challenge describing the authentication failure.
application/json ErrorResponse
409 The request conflicts with the resource's current state: an existing entry, a reused idempotency key, or a run that has already started.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
429 The plan rate limit was exceeded.
Headers
  • X-Request-Id string Unique request identifier.
  • Retry-After integer Seconds to wait before retrying.
  • RateLimit string Current rate-limit state.
  • RateLimit-Policy string Rate-limit policy for the current plan.
application/json ErrorResponse
500 An unexpected server error occurred.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
cURL example
curl -X POST "https://app.geartrain.dev/api/v1/jobs" \
  -H "Authorization: Bearer $GEARTRAIN_API_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{}'
GET /jobs/{jobId} jobs:read

Get a job

Requires the jobs:read scope.

Parameters

Name In Type Description
jobId* path integer Format: int64

Responses

Status Description Schema
200 Job details.
Headers
  • X-Request-Id string Unique request identifier.
  • RateLimit string Current rate-limit state.
  • RateLimit-Policy string Rate-limit policy for the current plan.
application/json JobResponse
400 The request is missing or invalid.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
401 Missing, invalid, expired, or revoked bearer token.
Headers
  • X-Request-Id string Unique request identifier.
  • WWW-Authenticate string Bearer challenge describing the authentication failure.
application/json ErrorResponse
403 The token does not grant the required scope or plan quota.
Headers
  • X-Request-Id string Unique request identifier.
  • WWW-Authenticate string Bearer challenge describing the authentication failure.
application/json ErrorResponse
404 The resource does not exist or is not owned by the user.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
429 The plan rate limit was exceeded.
Headers
  • X-Request-Id string Unique request identifier.
  • Retry-After integer Seconds to wait before retrying.
  • RateLimit string Current rate-limit state.
  • RateLimit-Policy string Rate-limit policy for the current plan.
application/json ErrorResponse
500 An unexpected server error occurred.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
cURL example
curl -X GET "https://app.geartrain.dev/api/v1/jobs/{jobId}" \
  -H "Authorization: Bearer $GEARTRAIN_API_TOKEN"
PATCH /jobs/{jobId} jobs:write

Update a job

Requires the jobs:write scope.

Parameters

Name In Type Description
jobId* path integer Format: int64

Request body Required

Content type Schema
application/json UpdateJobRequest

Responses

Status Description Schema
200 Updated job.
Headers
  • X-Request-Id string Unique request identifier.
  • RateLimit string Current rate-limit state.
  • RateLimit-Policy string Rate-limit policy for the current plan.
application/json JobResponse
400 The request is missing or invalid.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
401 Missing, invalid, expired, or revoked bearer token.
Headers
  • X-Request-Id string Unique request identifier.
  • WWW-Authenticate string Bearer challenge describing the authentication failure.
application/json ErrorResponse
403 The token does not grant the required scope or plan quota.
Headers
  • X-Request-Id string Unique request identifier.
  • WWW-Authenticate string Bearer challenge describing the authentication failure.
application/json ErrorResponse
404 The resource does not exist or is not owned by the user.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
429 The plan rate limit was exceeded.
Headers
  • X-Request-Id string Unique request identifier.
  • Retry-After integer Seconds to wait before retrying.
  • RateLimit string Current rate-limit state.
  • RateLimit-Policy string Rate-limit policy for the current plan.
application/json ErrorResponse
500 An unexpected server error occurred.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
cURL example
curl -X PATCH "https://app.geartrain.dev/api/v1/jobs/{jobId}" \
  -H "Authorization: Bearer $GEARTRAIN_API_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{}'
DELETE /jobs/{jobId} jobs:write

Delete a job

Requires the jobs:write scope. This is a soft delete: the job is hidden from the default list, its schedule is removed, and its run history is retained. Use GET /jobs?status=deleted to list deleted jobs.

Parameters

Name In Type Description
jobId* path integer Format: int64

Responses

Status Description Schema
200 Job deleted.
Headers
  • X-Request-Id string Unique request identifier.
  • RateLimit string Current rate-limit state.
  • RateLimit-Policy string Rate-limit policy for the current plan.
application/json ChangedResponse
400 The request is missing or invalid.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
401 Missing, invalid, expired, or revoked bearer token.
Headers
  • X-Request-Id string Unique request identifier.
  • WWW-Authenticate string Bearer challenge describing the authentication failure.
application/json ErrorResponse
403 The token does not grant the required scope or plan quota.
Headers
  • X-Request-Id string Unique request identifier.
  • WWW-Authenticate string Bearer challenge describing the authentication failure.
application/json ErrorResponse
404 The resource does not exist or is not owned by the user.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
429 The plan rate limit was exceeded.
Headers
  • X-Request-Id string Unique request identifier.
  • Retry-After integer Seconds to wait before retrying.
  • RateLimit string Current rate-limit state.
  • RateLimit-Policy string Rate-limit policy for the current plan.
application/json ErrorResponse
500 An unexpected server error occurred.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
cURL example
curl -X DELETE "https://app.geartrain.dev/api/v1/jobs/{jobId}" \
  -H "Authorization: Bearer $GEARTRAIN_API_TOKEN"
POST /jobs/{jobId}/pause jobs:write

Pause a job

Requires the jobs:write scope.

Parameters

Name In Type Description
jobId* path integer Format: int64

Responses

Status Description Schema
200 Job paused.
Headers
  • X-Request-Id string Unique request identifier.
  • RateLimit string Current rate-limit state.
  • RateLimit-Policy string Rate-limit policy for the current plan.
application/json ChangedResponse
400 The request is missing or invalid.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
401 Missing, invalid, expired, or revoked bearer token.
Headers
  • X-Request-Id string Unique request identifier.
  • WWW-Authenticate string Bearer challenge describing the authentication failure.
application/json ErrorResponse
403 The token does not grant the required scope or plan quota.
Headers
  • X-Request-Id string Unique request identifier.
  • WWW-Authenticate string Bearer challenge describing the authentication failure.
application/json ErrorResponse
404 The resource does not exist or is not owned by the user.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
429 The plan rate limit was exceeded.
Headers
  • X-Request-Id string Unique request identifier.
  • Retry-After integer Seconds to wait before retrying.
  • RateLimit string Current rate-limit state.
  • RateLimit-Policy string Rate-limit policy for the current plan.
application/json ErrorResponse
500 An unexpected server error occurred.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
cURL example
curl -X POST "https://app.geartrain.dev/api/v1/jobs/{jobId}/pause" \
  -H "Authorization: Bearer $GEARTRAIN_API_TOKEN"
POST /jobs/{jobId}/resume jobs:write

Resume a job

Requires the jobs:write scope.

Parameters

Name In Type Description
jobId* path integer Format: int64

Responses

Status Description Schema
200 Job resumed.
Headers
  • X-Request-Id string Unique request identifier.
  • RateLimit string Current rate-limit state.
  • RateLimit-Policy string Rate-limit policy for the current plan.
application/json ChangedResponse
400 The request is missing or invalid.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
401 Missing, invalid, expired, or revoked bearer token.
Headers
  • X-Request-Id string Unique request identifier.
  • WWW-Authenticate string Bearer challenge describing the authentication failure.
application/json ErrorResponse
403 The token does not grant the required scope or plan quota.
Headers
  • X-Request-Id string Unique request identifier.
  • WWW-Authenticate string Bearer challenge describing the authentication failure.
application/json ErrorResponse
404 The resource does not exist or is not owned by the user.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
429 The plan rate limit was exceeded.
Headers
  • X-Request-Id string Unique request identifier.
  • Retry-After integer Seconds to wait before retrying.
  • RateLimit string Current rate-limit state.
  • RateLimit-Policy string Rate-limit policy for the current plan.
application/json ErrorResponse
500 An unexpected server error occurred.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
cURL example
curl -X POST "https://app.geartrain.dev/api/v1/jobs/{jobId}/resume" \
  -H "Authorization: Bearer $GEARTRAIN_API_TOKEN"
POST /jobs/{jobId}/runs jobs:run

Queue a manual run

Requires the jobs:run scope. The run counts toward the monthly run quota. Manual runs are exempt from the plan’s concurrent-run cap and are limited to 5 per minute and 100 per day per user. Supply an Idempotency-Key to make retries safe.

Parameters

Name In Type Description
jobId* path integer Format: int64
Idempotency-Key header string Optional key for safe retries. Reusing the key with the same request replays the original response.

Request body

Content type Schema
application/json RunJobRequest

Responses

Status Description Schema
202 Run queued.
Headers
  • X-Request-Id string Unique request identifier.
  • Idempotency-Replayed boolean Present and true when a stored idempotent response was replayed.
  • RateLimit string Current rate-limit state.
  • RateLimit-Policy string Rate-limit policy for the current plan.
application/json RunQueuedResponse
400 The request is missing or invalid.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
401 Missing, invalid, expired, or revoked bearer token.
Headers
  • X-Request-Id string Unique request identifier.
  • WWW-Authenticate string Bearer challenge describing the authentication failure.
application/json ErrorResponse
403 The token does not grant the required scope or plan quota.
Headers
  • X-Request-Id string Unique request identifier.
  • WWW-Authenticate string Bearer challenge describing the authentication failure.
application/json ErrorResponse
404 The resource does not exist or is not owned by the user.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
429 The plan rate limit was exceeded.
Headers
  • X-Request-Id string Unique request identifier.
  • Retry-After integer Seconds to wait before retrying.
  • RateLimit string Current rate-limit state.
  • RateLimit-Policy string Rate-limit policy for the current plan.
application/json ErrorResponse
500 An unexpected server error occurred.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
cURL example
curl -X POST "https://app.geartrain.dev/api/v1/jobs/{jobId}/runs" \
  -H "Authorization: Bearer $GEARTRAIN_API_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{}'

Webhooks

Producer-supplied webhook credentials attached to a job.

GET /jobs/{jobId}/webhooks jobs:read

List a job's webhook endpoints

Requires the jobs:read scope. Returns every active endpoint for the job. Secrets are never returned.

Parameters

Name In Type Description
jobId* path integer Format: int64

Responses

Status Description Schema
200 Webhook endpoints.
Headers
  • X-Request-Id string Unique request identifier.
  • RateLimit string Current rate-limit state.
  • RateLimit-Policy string Rate-limit policy for the current plan.
application/json WebhookEndpointListResponse
400 The request is missing or invalid.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
401 Missing, invalid, expired, or revoked bearer token.
Headers
  • X-Request-Id string Unique request identifier.
  • WWW-Authenticate string Bearer challenge describing the authentication failure.
application/json ErrorResponse
403 The token does not grant the required scope or plan quota.
Headers
  • X-Request-Id string Unique request identifier.
  • WWW-Authenticate string Bearer challenge describing the authentication failure.
application/json ErrorResponse
404 The resource does not exist or is not owned by the user.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
429 The plan rate limit was exceeded.
Headers
  • X-Request-Id string Unique request identifier.
  • Retry-After integer Seconds to wait before retrying.
  • RateLimit string Current rate-limit state.
  • RateLimit-Policy string Rate-limit policy for the current plan.
application/json ErrorResponse
500 An unexpected server error occurred.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
cURL example
curl -X GET "https://app.geartrain.dev/api/v1/jobs/{jobId}/webhooks" \
  -H "Authorization: Bearer $GEARTRAIN_API_TOKEN"
POST /jobs/{jobId}/webhooks jobs:write

Add a webhook endpoint

Requires the jobs:write scope. The caller supplies the credentials the source needs. Standard Webhooks requires whsec_ followed by base64 that decodes to 24 to 64 bytes; an invalid secret returns 400 with code invalid_secret. Stripe accepts its whsec_ signing secret. Shopify, GitHub, Square, Typeform, Calendly, Slack, HubSpot, Paddle, Zendesk, API key, and generic HMAC accept an arbitrary shared string. Generic HMAC and API key also accept a verification object. unverified needs no secret; a supplied secret is ignored. See Webhook Verification for the method details. The secret is encrypted at rest and never returned. A job may have up to 10 active endpoints; a create beyond that limit returns 400 with code limit_reached. Supply an Idempotency-Key to make retries safe.

Parameters

Name In Type Description
jobId* path integer Format: int64
Idempotency-Key header string Optional key for safe retries. Reusing the key with the same request replays the original response.

Request body Required

Content type Schema
application/json CreateWebhookRequest

Responses

Status Description Schema
201 Webhook endpoint created.
Headers
  • X-Request-Id string Unique request identifier.
  • Idempotency-Replayed boolean Present and true when a stored idempotent response was replayed.
  • RateLimit string Current rate-limit state.
  • RateLimit-Policy string Rate-limit policy for the current plan.
application/json WebhookEndpointResponse
400 The request is missing or invalid.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
401 Missing, invalid, expired, or revoked bearer token.
Headers
  • X-Request-Id string Unique request identifier.
  • WWW-Authenticate string Bearer challenge describing the authentication failure.
application/json ErrorResponse
403 The token does not grant the required scope or plan quota.
Headers
  • X-Request-Id string Unique request identifier.
  • WWW-Authenticate string Bearer challenge describing the authentication failure.
application/json ErrorResponse
404 The resource does not exist or is not owned by the user.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
429 The plan rate limit was exceeded.
Headers
  • X-Request-Id string Unique request identifier.
  • Retry-After integer Seconds to wait before retrying.
  • RateLimit string Current rate-limit state.
  • RateLimit-Policy string Rate-limit policy for the current plan.
application/json ErrorResponse
500 An unexpected server error occurred.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
cURL example
curl -X POST "https://app.geartrain.dev/api/v1/jobs/{jobId}/webhooks" \
  -H "Authorization: Bearer $GEARTRAIN_API_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{}'
GET /jobs/{jobId}/webhooks/{endpointId} jobs:read

Get a webhook endpoint

Requires the jobs:read scope. Secrets are never returned.

Parameters

Name In Type Description
jobId* path integer Format: int64
endpointId* path string Opaque webhook endpoint ID.

Responses

Status Description Schema
200 Webhook endpoint.
Headers
  • X-Request-Id string Unique request identifier.
  • RateLimit string Current rate-limit state.
  • RateLimit-Policy string Rate-limit policy for the current plan.
application/json WebhookEndpointResponse
400 The request is missing or invalid.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
401 Missing, invalid, expired, or revoked bearer token.
Headers
  • X-Request-Id string Unique request identifier.
  • WWW-Authenticate string Bearer challenge describing the authentication failure.
application/json ErrorResponse
403 The token does not grant the required scope or plan quota.
Headers
  • X-Request-Id string Unique request identifier.
  • WWW-Authenticate string Bearer challenge describing the authentication failure.
application/json ErrorResponse
404 The resource does not exist or is not owned by the user.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
429 The plan rate limit was exceeded.
Headers
  • X-Request-Id string Unique request identifier.
  • Retry-After integer Seconds to wait before retrying.
  • RateLimit string Current rate-limit state.
  • RateLimit-Policy string Rate-limit policy for the current plan.
application/json ErrorResponse
500 An unexpected server error occurred.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
cURL example
curl -X GET "https://app.geartrain.dev/api/v1/jobs/{jobId}/webhooks/{endpointId}" \
  -H "Authorization: Bearer $GEARTRAIN_API_TOKEN"
PATCH /jobs/{jobId}/webhooks/{endpointId} jobs:write

Rename or enable a webhook endpoint

Requires the jobs:write scope. Omitted fields keep their current values. Set name to null to clear it.

Parameters

Name In Type Description
jobId* path integer Format: int64
endpointId* path string Opaque webhook endpoint ID.

Request body Required

Content type Schema
application/json UpdateWebhookRequest

Responses

Status Description Schema
200 Updated webhook endpoint.
Headers
  • X-Request-Id string Unique request identifier.
  • RateLimit string Current rate-limit state.
  • RateLimit-Policy string Rate-limit policy for the current plan.
application/json WebhookEndpointResponse
400 The request is missing or invalid.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
401 Missing, invalid, expired, or revoked bearer token.
Headers
  • X-Request-Id string Unique request identifier.
  • WWW-Authenticate string Bearer challenge describing the authentication failure.
application/json ErrorResponse
403 The token does not grant the required scope or plan quota.
Headers
  • X-Request-Id string Unique request identifier.
  • WWW-Authenticate string Bearer challenge describing the authentication failure.
application/json ErrorResponse
404 The resource does not exist or is not owned by the user.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
429 The plan rate limit was exceeded.
Headers
  • X-Request-Id string Unique request identifier.
  • Retry-After integer Seconds to wait before retrying.
  • RateLimit string Current rate-limit state.
  • RateLimit-Policy string Rate-limit policy for the current plan.
application/json ErrorResponse
500 An unexpected server error occurred.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
cURL example
curl -X PATCH "https://app.geartrain.dev/api/v1/jobs/{jobId}/webhooks/{endpointId}" \
  -H "Authorization: Bearer $GEARTRAIN_API_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{}'
DELETE /jobs/{jobId}/webhooks/{endpointId} jobs:write

Delete a webhook endpoint

Requires the jobs:write scope. Tombstones the endpoint and destroys its secret. Other endpoints for the job keep working.

Parameters

Name In Type Description
jobId* path integer Format: int64
endpointId* path string Opaque webhook endpoint ID.

Responses

Status Description Schema
200 Webhook endpoint deleted.
Headers
  • X-Request-Id string Unique request identifier.
  • RateLimit string Current rate-limit state.
  • RateLimit-Policy string Rate-limit policy for the current plan.
application/json ChangedResponse
400 The request is missing or invalid.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
401 Missing, invalid, expired, or revoked bearer token.
Headers
  • X-Request-Id string Unique request identifier.
  • WWW-Authenticate string Bearer challenge describing the authentication failure.
application/json ErrorResponse
403 The token does not grant the required scope or plan quota.
Headers
  • X-Request-Id string Unique request identifier.
  • WWW-Authenticate string Bearer challenge describing the authentication failure.
application/json ErrorResponse
404 The resource does not exist or is not owned by the user.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
429 The plan rate limit was exceeded.
Headers
  • X-Request-Id string Unique request identifier.
  • Retry-After integer Seconds to wait before retrying.
  • RateLimit string Current rate-limit state.
  • RateLimit-Policy string Rate-limit policy for the current plan.
application/json ErrorResponse
500 An unexpected server error occurred.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
cURL example
curl -X DELETE "https://app.geartrain.dev/api/v1/jobs/{jobId}/webhooks/{endpointId}" \
  -H "Authorization: Bearer $GEARTRAIN_API_TOKEN"

Runs

Run history, details, and deletion.

GET /runs runs:read

List runs

Requires the runs:read scope. Results are newest first.

Queued runs accepted by POST /jobs/{jobId}/runs are included with status: queued until execution starts.

The status filter matches derived statuses, so a page can contain fewer than limit items. Keep following data.pagination.nextCursor while hasMore is true.

An unknown or foreign jobId filter returns 404 job_not_found. An owned deleted job with no runs returns an empty list.

Parameters

Name In Type Description
jobId query integer Restrict to one job. Unknown or foreign jobs return 404. Format: int64
status query string Restrict to one derived run status. Allowed: queued, running, retrying, success, error, timeout, interrupted, unknown
trigger query string Restrict to one run trigger. Allowed: manual, schedule, webhook
since query string Include runs started at or after this date or timestamp. A date-only value is interpreted in the account timezone.
until query string Include runs started at or before this date or timestamp. A date-only value covers the whole day in the account timezone.
limit query integer Number of items to return. Default: 20
cursor query string Opaque cursor from `data.pagination.nextCursor`.

Responses

Status Description Schema
200 Run summaries.
Headers
  • X-Request-Id string Unique request identifier.
  • RateLimit string Current rate-limit state.
  • RateLimit-Policy string Rate-limit policy for the current plan.
application/json RunListResponse
400 The request is missing or invalid.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
401 Missing, invalid, expired, or revoked bearer token.
Headers
  • X-Request-Id string Unique request identifier.
  • WWW-Authenticate string Bearer challenge describing the authentication failure.
application/json ErrorResponse
403 The token does not grant the required scope or plan quota.
Headers
  • X-Request-Id string Unique request identifier.
  • WWW-Authenticate string Bearer challenge describing the authentication failure.
application/json ErrorResponse
404 The resource does not exist or is not owned by the user.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
429 The plan rate limit was exceeded.
Headers
  • X-Request-Id string Unique request identifier.
  • Retry-After integer Seconds to wait before retrying.
  • RateLimit string Current rate-limit state.
  • RateLimit-Policy string Rate-limit policy for the current plan.
application/json ErrorResponse
500 An unexpected server error occurred.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
cURL example
curl -X GET "https://app.geartrain.dev/api/v1/runs" \
  -H "Authorization: Bearer $GEARTRAIN_API_TOKEN"
GET /runs/{runId}/logs runs:read

List run console entries

Requires the runs:read scope.

Returns a page of console entries. Without after, the page is the tail of the run. Pass the previous response’s nextCursor as after to fetch only entries inserted since that call. Entries are returned in insertion order and include their attempt number. Unknown, deleted, and other users’ run IDs return 404.

Parameters

Name In Type Description
runId* path string Format: uuid
after query string Cursor from a previous response.
limit query integer Maximum entries to return. Default: 100

Responses

Status Description Schema
200 A page of console entries.
Headers
  • X-Request-Id string Unique request identifier.
  • RateLimit string Current rate-limit state.
  • RateLimit-Policy string Rate-limit policy for the current plan.
application/json RunLogsResponse
400 The request is missing or invalid.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
401 Missing, invalid, expired, or revoked bearer token.
Headers
  • X-Request-Id string Unique request identifier.
  • WWW-Authenticate string Bearer challenge describing the authentication failure.
application/json ErrorResponse
403 The token does not grant the required scope or plan quota.
Headers
  • X-Request-Id string Unique request identifier.
  • WWW-Authenticate string Bearer challenge describing the authentication failure.
application/json ErrorResponse
404 The resource does not exist or is not owned by the user.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
429 The plan rate limit was exceeded.
Headers
  • X-Request-Id string Unique request identifier.
  • Retry-After integer Seconds to wait before retrying.
  • RateLimit string Current rate-limit state.
  • RateLimit-Policy string Rate-limit policy for the current plan.
application/json ErrorResponse
500 An unexpected server error occurred.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
cURL example
curl -X GET "https://app.geartrain.dev/api/v1/runs/{runId}/logs" \
  -H "Authorization: Bearer $GEARTRAIN_API_TOKEN"
GET /runs/{runId} runs:read

Get a run

Requires the runs:read scope.

A run is readable as soon as it is accepted. Until the executor records the first event it returns status: queued with jobId and jobName set to null; the association becomes available once execution starts. queued does not guarantee that DELETE can still cancel the run: the executor may already have claimed it. Unknown, deleted, and other users’ run IDs return 404.

Console entries are bounded per attempt. includeLogs defaults to true and logLines defaults to 100 with a maximum of 500. Use GET /runs/{runId}/logs to follow a running run without re-reading output.

Parameters

Name In Type Description
runId* path string Format: uuid
includeLogs query boolean Set to false to omit console entries. Default: true
logLines query integer Console entries returned per attempt. Default: 100

Responses

Status Description Schema
200 Run details, attempts, and console entries.
Headers
  • X-Request-Id string Unique request identifier.
  • RateLimit string Current rate-limit state.
  • RateLimit-Policy string Rate-limit policy for the current plan.
application/json RunDetailResponse
400 The request is missing or invalid.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
401 Missing, invalid, expired, or revoked bearer token.
Headers
  • X-Request-Id string Unique request identifier.
  • WWW-Authenticate string Bearer challenge describing the authentication failure.
application/json ErrorResponse
403 The token does not grant the required scope or plan quota.
Headers
  • X-Request-Id string Unique request identifier.
  • WWW-Authenticate string Bearer challenge describing the authentication failure.
application/json ErrorResponse
404 The resource does not exist or is not owned by the user.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
429 The plan rate limit was exceeded.
Headers
  • X-Request-Id string Unique request identifier.
  • Retry-After integer Seconds to wait before retrying.
  • RateLimit string Current rate-limit state.
  • RateLimit-Policy string Rate-limit policy for the current plan.
application/json ErrorResponse
500 An unexpected server error occurred.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
cURL example
curl -X GET "https://app.geartrain.dev/api/v1/runs/{runId}" \
  -H "Authorization: Bearer $GEARTRAIN_API_TOKEN"
DELETE /runs/{runId} runs:write

Delete a run

Requires the runs:write scope. Deleting a finished run removes its events and logs. Deleting a queued run cancels it if the executor has not claimed it yet. A run that has already started is left intact and returns 409 with code run_already_started. Unknown runs return 404.

Parameters

Name In Type Description
runId* path string Format: uuid

Responses

Status Description Schema
200 Run deleted.
Headers
  • X-Request-Id string Unique request identifier.
  • RateLimit string Current rate-limit state.
  • RateLimit-Policy string Rate-limit policy for the current plan.
application/json ChangedResponse
400 The request is missing or invalid.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
401 Missing, invalid, expired, or revoked bearer token.
Headers
  • X-Request-Id string Unique request identifier.
  • WWW-Authenticate string Bearer challenge describing the authentication failure.
application/json ErrorResponse
403 The token does not grant the required scope or plan quota.
Headers
  • X-Request-Id string Unique request identifier.
  • WWW-Authenticate string Bearer challenge describing the authentication failure.
application/json ErrorResponse
404 The resource does not exist or is not owned by the user.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
409 The request conflicts with the resource's current state: an existing entry, a reused idempotency key, or a run that has already started.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
429 The plan rate limit was exceeded.
Headers
  • X-Request-Id string Unique request identifier.
  • Retry-After integer Seconds to wait before retrying.
  • RateLimit string Current rate-limit state.
  • RateLimit-Policy string Rate-limit policy for the current plan.
application/json ErrorResponse
500 An unexpected server error occurred.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
cURL example
curl -X DELETE "https://app.geartrain.dev/api/v1/runs/{runId}" \
  -H "Authorization: Bearer $GEARTRAIN_API_TOKEN"

Files

Script files and folders in the user file system.

Content has two shapes:

  • /files/content is JSON. Reads return a string (UTF-8 text, or base64 for binary); writes accept a UTF-8 string at an exact path. Use it for scripts, configuration, and small edits.
  • /files/upload and /files/download are binary. They use multipart and raw octet-stream bodies and are bounded only by plan storage. Use them for images, archives, and large files.
GET /files files:read

List a directory

Requires the files:read scope.

Parameters

Name In Type Description
path query string URL-encoded absolute directory path. Defaults to the root directory. Default: /

Responses

Status Description Schema
200 Directory listing.
Headers
  • X-Request-Id string Unique request identifier.
  • RateLimit string Current rate-limit state.
  • RateLimit-Policy string Rate-limit policy for the current plan.
application/json DirectoryListingResponse
401 Missing, invalid, expired, or revoked bearer token.
Headers
  • X-Request-Id string Unique request identifier.
  • WWW-Authenticate string Bearer challenge describing the authentication failure.
application/json ErrorResponse
403 The token does not grant the required scope or plan quota.
Headers
  • X-Request-Id string Unique request identifier.
  • WWW-Authenticate string Bearer challenge describing the authentication failure.
application/json ErrorResponse
404 The resource does not exist or is not owned by the user.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
429 The plan rate limit was exceeded.
Headers
  • X-Request-Id string Unique request identifier.
  • Retry-After integer Seconds to wait before retrying.
  • RateLimit string Current rate-limit state.
  • RateLimit-Policy string Rate-limit policy for the current plan.
application/json ErrorResponse
500 An unexpected server error occurred.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
cURL example
curl -X GET "https://app.geartrain.dev/api/v1/files" \
  -H "Authorization: Bearer $GEARTRAIN_API_TOKEN"
POST /files files:write

Create a file or folder

Requires the files:write scope. The parent path must be an existing directory; a missing parent returns 404 and a parent that is a file returns 400.

Parameters

Name In Type Description
Idempotency-Key header string Optional key for safe retries. Reusing the key with the same request replays the original response.

Request body Required

Content type Schema
application/json CreateFileRequest

Responses

Status Description Schema
201 Entry created.
Headers
  • X-Request-Id string Unique request identifier.
  • Idempotency-Replayed boolean Present and true when a stored idempotent response was replayed.
  • RateLimit string Current rate-limit state.
  • RateLimit-Policy string Rate-limit policy for the current plan.
application/json CreateFileResponse
400 The request is missing or invalid.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
401 Missing, invalid, expired, or revoked bearer token.
Headers
  • X-Request-Id string Unique request identifier.
  • WWW-Authenticate string Bearer challenge describing the authentication failure.
application/json ErrorResponse
403 The token does not grant the required scope or plan quota.
Headers
  • X-Request-Id string Unique request identifier.
  • WWW-Authenticate string Bearer challenge describing the authentication failure.
application/json ErrorResponse
404 The resource does not exist or is not owned by the user.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
409 The request conflicts with the resource's current state: an existing entry, a reused idempotency key, or a run that has already started.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
429 The plan rate limit was exceeded.
Headers
  • X-Request-Id string Unique request identifier.
  • Retry-After integer Seconds to wait before retrying.
  • RateLimit string Current rate-limit state.
  • RateLimit-Policy string Rate-limit policy for the current plan.
application/json ErrorResponse
500 An unexpected server error occurred.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
cURL example
curl -X POST "https://app.geartrain.dev/api/v1/files" \
  -H "Authorization: Bearer $GEARTRAIN_API_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{}'
DELETE /files files:write

Delete a file or folder

Requires the files:write scope. Files and empty folders delete directly. A non-empty folder requires recursive=true.

Parameters

Name In Type Description
path* query string URL-encoded absolute path to delete.
recursive query boolean Required to delete a non-empty folder and its contents. Default: false

Responses

Status Description Schema
200 Entry deleted.
Headers
  • X-Request-Id string Unique request identifier.
  • RateLimit string Current rate-limit state.
  • RateLimit-Policy string Rate-limit policy for the current plan.
application/json ChangedResponse
401 Missing, invalid, expired, or revoked bearer token.
Headers
  • X-Request-Id string Unique request identifier.
  • WWW-Authenticate string Bearer challenge describing the authentication failure.
application/json ErrorResponse
403 The token does not grant the required scope or plan quota.
Headers
  • X-Request-Id string Unique request identifier.
  • WWW-Authenticate string Bearer challenge describing the authentication failure.
application/json ErrorResponse
404 The resource does not exist or is not owned by the user.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
429 The plan rate limit was exceeded.
Headers
  • X-Request-Id string Unique request identifier.
  • Retry-After integer Seconds to wait before retrying.
  • RateLimit string Current rate-limit state.
  • RateLimit-Policy string Rate-limit policy for the current plan.
application/json ErrorResponse
500 An unexpected server error occurred.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
cURL example
curl -X DELETE "https://app.geartrain.dev/api/v1/files" \
  -H "Authorization: Bearer $GEARTRAIN_API_TOKEN"
GET /files/content files:read

Read a file

Requires the files:read scope. Text files are returned as UTF-8; binary files use base64 encoding.

offset starts at a byte position and maxBytes caps the returned chunk. Responses are capped at 10 MiB (10,485,760 bytes) when no chunk is requested. Use /files/download for larger files.

Set metadataOnly=true to return path, type, size, and modification time without reading content. It cannot be combined with offset or maxBytes.

Parameters

Name In Type Description
path* query string URL-encoded absolute file or folder path.
offset query integer Starting byte offset for a content read. Default: 0
maxBytes query integer Maximum bytes to return; capped at 1 MiB.
metadataOnly query boolean Return metadata without reading content. Default: false

Responses

Status Description Schema
200 File content or metadata.
Headers
  • X-Request-Id string Unique request identifier.
  • RateLimit string Current rate-limit state.
  • RateLimit-Policy string Rate-limit policy for the current plan.
application/json FileContentResponse | FileMetadataResponse
401 Missing, invalid, expired, or revoked bearer token.
Headers
  • X-Request-Id string Unique request identifier.
  • WWW-Authenticate string Bearer challenge describing the authentication failure.
application/json ErrorResponse
403 The token does not grant the required scope or plan quota.
Headers
  • X-Request-Id string Unique request identifier.
  • WWW-Authenticate string Bearer challenge describing the authentication failure.
application/json ErrorResponse
404 The resource does not exist or is not owned by the user.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
413 The request body exceeds the allowed limit.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
429 The plan rate limit was exceeded.
Headers
  • X-Request-Id string Unique request identifier.
  • Retry-After integer Seconds to wait before retrying.
  • RateLimit string Current rate-limit state.
  • RateLimit-Policy string Rate-limit policy for the current plan.
application/json ErrorResponse
500 An unexpected server error occurred.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
cURL example
curl -X GET "https://app.geartrain.dev/api/v1/files/content" \
  -H "Authorization: Bearer $GEARTRAIN_API_TOKEN"
PUT /files/content files:write

Write a file

Requires the files:write scope. Creates the file when missing and replaces its content in place otherwise. The absolute path is supplied in the JSON body, not the URL.

The parent directory must already exist. The JSON request body is capped at 1 MiB (1,048,576 bytes), so the content string must be smaller; use /files/upload for binary or larger content.

Request body Required

Content type Schema
application/json FileWriteRequest

Responses

Status Description Schema
200 File saved.
Headers
  • X-Request-Id string Unique request identifier.
  • RateLimit string Current rate-limit state.
  • RateLimit-Policy string Rate-limit policy for the current plan.
application/json FileSavedResponse
400 The request is missing or invalid.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
401 Missing, invalid, expired, or revoked bearer token.
Headers
  • X-Request-Id string Unique request identifier.
  • WWW-Authenticate string Bearer challenge describing the authentication failure.
application/json ErrorResponse
403 The token does not grant the required scope or plan quota.
Headers
  • X-Request-Id string Unique request identifier.
  • WWW-Authenticate string Bearer challenge describing the authentication failure.
application/json ErrorResponse
404 The resource does not exist or is not owned by the user.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
413 The request body exceeds the allowed limit.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
429 The plan rate limit was exceeded.
Headers
  • X-Request-Id string Unique request identifier.
  • Retry-After integer Seconds to wait before retrying.
  • RateLimit string Current rate-limit state.
  • RateLimit-Policy string Rate-limit policy for the current plan.
application/json ErrorResponse
500 An unexpected server error occurred.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
cURL example
curl -X PUT "https://app.geartrain.dev/api/v1/files/content" \
  -H "Authorization: Bearer $GEARTRAIN_API_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{}'
POST /files/rename files:write

Rename or move a file or folder

Requires the files:write scope. destination is the full absolute path, including the final name. Existing targets are rejected. Job script paths are updated on a best-effort basis; jobsUpdateError reports a failure after the file or folder has already moved.

Request body Required

Content type Schema
application/json RenameFileRequest

Responses

Status Description Schema
200 Entry renamed.
Headers
  • X-Request-Id string Unique request identifier.
  • RateLimit string Current rate-limit state.
  • RateLimit-Policy string Rate-limit policy for the current plan.
application/json RenameFileResponse
400 The request is missing or invalid.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
401 Missing, invalid, expired, or revoked bearer token.
Headers
  • X-Request-Id string Unique request identifier.
  • WWW-Authenticate string Bearer challenge describing the authentication failure.
application/json ErrorResponse
403 The token does not grant the required scope or plan quota.
Headers
  • X-Request-Id string Unique request identifier.
  • WWW-Authenticate string Bearer challenge describing the authentication failure.
application/json ErrorResponse
404 The resource does not exist or is not owned by the user.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
409 The request conflicts with the resource's current state: an existing entry, a reused idempotency key, or a run that has already started.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
429 The plan rate limit was exceeded.
Headers
  • X-Request-Id string Unique request identifier.
  • Retry-After integer Seconds to wait before retrying.
  • RateLimit string Current rate-limit state.
  • RateLimit-Policy string Rate-limit policy for the current plan.
application/json ErrorResponse
500 An unexpected server error occurred.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
cURL example
curl -X POST "https://app.geartrain.dev/api/v1/files/rename" \
  -H "Authorization: Bearer $GEARTRAIN_API_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{}'
POST /files/upload files:write

Upload a file

Requires the files:write scope. Accepts multipart/form-data with one file part.

The entry is created at parentPath + the file part’s filename, or at parentPath + name when name is supplied. The parent directory must already exist. Uploads are bounded by the plan’s remaining storage. An existing entry at the target path returns 409; rename or delete it first, or choose another name. Use /files/content when writing text to an exact path.

Request body Required

Content type Schema
multipart/form-data UploadFileRequest

Responses

Status Description Schema
201 File uploaded.
Headers
  • X-Request-Id string Unique request identifier.
  • RateLimit string Current rate-limit state.
  • RateLimit-Policy string Rate-limit policy for the current plan.
application/json CreateFileResponse
400 The request is missing or invalid.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
401 Missing, invalid, expired, or revoked bearer token.
Headers
  • X-Request-Id string Unique request identifier.
  • WWW-Authenticate string Bearer challenge describing the authentication failure.
application/json ErrorResponse
403 The token does not grant the required scope or plan quota.
Headers
  • X-Request-Id string Unique request identifier.
  • WWW-Authenticate string Bearer challenge describing the authentication failure.
application/json ErrorResponse
404 The resource does not exist or is not owned by the user.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
409 The request conflicts with the resource's current state: an existing entry, a reused idempotency key, or a run that has already started.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
413 The request body exceeds the allowed limit.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
429 The plan rate limit was exceeded.
Headers
  • X-Request-Id string Unique request identifier.
  • Retry-After integer Seconds to wait before retrying.
  • RateLimit string Current rate-limit state.
  • RateLimit-Policy string Rate-limit policy for the current plan.
application/json ErrorResponse
500 An unexpected server error occurred.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
cURL example
curl -X POST "https://app.geartrain.dev/api/v1/files/upload" \
  -H "Authorization: Bearer $GEARTRAIN_API_TOKEN" \
  -F "file=@/path/to/file"
GET /files/download files:read

Download a file

Requires the files:read scope.

Parameters

Name In Type Description
path* query string URL-encoded absolute file path.

Responses

Status Description Schema
200 Raw file bytes.
Headers
  • X-Request-Id string Unique request identifier.
  • RateLimit string Current rate-limit state.
  • RateLimit-Policy string Rate-limit policy for the current plan.
application/octet-stream string
401 Missing, invalid, expired, or revoked bearer token.
Headers
  • X-Request-Id string Unique request identifier.
  • WWW-Authenticate string Bearer challenge describing the authentication failure.
application/json ErrorResponse
403 The token does not grant the required scope or plan quota.
Headers
  • X-Request-Id string Unique request identifier.
  • WWW-Authenticate string Bearer challenge describing the authentication failure.
application/json ErrorResponse
404 The resource does not exist or is not owned by the user.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
429 The plan rate limit was exceeded.
Headers
  • X-Request-Id string Unique request identifier.
  • Retry-After integer Seconds to wait before retrying.
  • RateLimit string Current rate-limit state.
  • RateLimit-Policy string Rate-limit policy for the current plan.
application/json ErrorResponse
500 An unexpected server error occurred.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
cURL example
curl -X GET "https://app.geartrain.dev/api/v1/files/download" \
  -H "Authorization: Bearer $GEARTRAIN_API_TOKEN"

Secrets

Write-only environment secrets for scripts.

GET /secrets secrets:read

List secrets

Requires the secrets:read scope. Secret values are write-only and are never returned.

Responses

Status Description Schema
200 Secret names and timestamps.
Headers
  • X-Request-Id string Unique request identifier.
  • RateLimit string Current rate-limit state.
  • RateLimit-Policy string Rate-limit policy for the current plan.
application/json SecretListResponse
401 Missing, invalid, expired, or revoked bearer token.
Headers
  • X-Request-Id string Unique request identifier.
  • WWW-Authenticate string Bearer challenge describing the authentication failure.
application/json ErrorResponse
403 The token does not grant the required scope or plan quota.
Headers
  • X-Request-Id string Unique request identifier.
  • WWW-Authenticate string Bearer challenge describing the authentication failure.
application/json ErrorResponse
429 The plan rate limit was exceeded.
Headers
  • X-Request-Id string Unique request identifier.
  • Retry-After integer Seconds to wait before retrying.
  • RateLimit string Current rate-limit state.
  • RateLimit-Policy string Rate-limit policy for the current plan.
application/json ErrorResponse
500 An unexpected server error occurred.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
cURL example
curl -X GET "https://app.geartrain.dev/api/v1/secrets" \
  -H "Authorization: Bearer $GEARTRAIN_API_TOKEN"
POST /secrets secrets:write

Create a secret

Requires the secrets:write scope. Names are unique per account; creating a duplicate returns 409.

Parameters

Name In Type Description
Idempotency-Key header string Optional key for safe retries. Reusing the key with the same request replays the original response.

Request body Required

Content type Schema
application/json CreateSecretRequest

Responses

Status Description Schema
201 Secret created. The value is not returned.
Headers
  • X-Request-Id string Unique request identifier.
  • Idempotency-Replayed boolean Present and true when a stored idempotent response was replayed.
  • RateLimit string Current rate-limit state.
  • RateLimit-Policy string Rate-limit policy for the current plan.
application/json SecretResponse
400 The request is missing or invalid.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
401 Missing, invalid, expired, or revoked bearer token.
Headers
  • X-Request-Id string Unique request identifier.
  • WWW-Authenticate string Bearer challenge describing the authentication failure.
application/json ErrorResponse
403 The token does not grant the required scope or plan quota.
Headers
  • X-Request-Id string Unique request identifier.
  • WWW-Authenticate string Bearer challenge describing the authentication failure.
application/json ErrorResponse
409 The request conflicts with the resource's current state: an existing entry, a reused idempotency key, or a run that has already started.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
429 The plan rate limit was exceeded.
Headers
  • X-Request-Id string Unique request identifier.
  • Retry-After integer Seconds to wait before retrying.
  • RateLimit string Current rate-limit state.
  • RateLimit-Policy string Rate-limit policy for the current plan.
application/json ErrorResponse
500 An unexpected server error occurred.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
cURL example
curl -X POST "https://app.geartrain.dev/api/v1/secrets" \
  -H "Authorization: Bearer $GEARTRAIN_API_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{}'
DELETE /secrets/{secretId} secrets:write

Delete a secret

Requires the secrets:write scope.

Parameters

Name In Type Description
secretId* path string Format: uuid

Responses

Status Description Schema
200 Secret deleted.
Headers
  • X-Request-Id string Unique request identifier.
  • RateLimit string Current rate-limit state.
  • RateLimit-Policy string Rate-limit policy for the current plan.
application/json ChangedResponse
400 The request is missing or invalid.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
401 Missing, invalid, expired, or revoked bearer token.
Headers
  • X-Request-Id string Unique request identifier.
  • WWW-Authenticate string Bearer challenge describing the authentication failure.
application/json ErrorResponse
403 The token does not grant the required scope or plan quota.
Headers
  • X-Request-Id string Unique request identifier.
  • WWW-Authenticate string Bearer challenge describing the authentication failure.
application/json ErrorResponse
404 The resource does not exist or is not owned by the user.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
429 The plan rate limit was exceeded.
Headers
  • X-Request-Id string Unique request identifier.
  • Retry-After integer Seconds to wait before retrying.
  • RateLimit string Current rate-limit state.
  • RateLimit-Policy string Rate-limit policy for the current plan.
application/json ErrorResponse
500 An unexpected server error occurred.
Headers
  • X-Request-Id string Unique request identifier.
application/json ErrorResponse
cURL example
curl -X DELETE "https://app.geartrain.dev/api/v1/secrets/{secretId}" \
  -H "Authorization: Bearer $GEARTRAIN_API_TOKEN"

Schemas

Schemas referenced by the operations above. Use the links in request, response, and property types to jump between definitions.

RequestId

string

Server-generated request identifier.

Warning

object

Property Type Description
code* string
message* string

Error

object

Property Type Description
code* string Stable machine-readable failure code.
message* string Human-readable failure description.
field string Field associated with a single validation error.
retryAfterSeconds integer

SuccessEnvelope

object

Property Type Description
ok* boolean
requestId* RequestId Server-generated request identifier.
data* object
warnings array<Warning>

ErrorResponse

object

Property Type Description
ok* boolean
requestId* RequestId Server-generated request identifier.
error* Error

Pagination

object

Property Type Description
limit* integer
nextCursor* string | null Cursor for the next page, or null when there is no next page.
hasMore* boolean

Scope

string

Permission granted to an API token.

Allowed values: jobs:read, jobs:write, jobs:run, runs:read, runs:write, files:read, files:write, secrets:read, secrets:write, account:read

JobStatus

string

Allowed values: active, paused, deleted

RunStatus

string

Allowed values: queued, running, retrying, success, error, timeout, interrupted, unknown

MeData

object

Property Type Description
userId* string
tokenId* string Format: uuid
tokenName* string
scopes* array<Scope>
expiresAt* integer Unix timestamp in milliseconds when the token expires. Format: int64

AccountResponse

SuccessEnvelope

Property Type Description
data object

Account

object

Property Type Description
id* string
email* string Format: email
emailVerified* boolean
plan* string Allowed: free, pro
theme* string Allowed: light, dark
timezone* string
logRetentionDays* integer Days to keep run logs and history. Capped by the account plan (3 on Free, 30 on Pro). Format: int32
otpEnabled* boolean
createdAt* string Format: date-time

JobsUsage

object

Property Type Description
used* integer Active jobs. Paused and soft-deleted jobs are excluded.
limit* integer Plan's active-job limit.

RunsUsage

object

Property Type Description
used* integer Runs metered in the current UTC month.
limit* integer Plan's monthly run limit.
period* string
resetsAt* string Start of the next UTC month. Format: date-time

StorageUsage

object

Property Type Description
usedBytes* integer | null Total measured content bytes, or null when unavailable.
limitBytes* integer
filesBytes* integer | null
logsBytes* integer | null
systemBytes* integer | null

Job

object

Property Type Description
id* integer Format: int64
name string | null
cron* string | null Cron schedule for the job, evaluated in the account's timezone; see Cron schedules. Omit or null for a manual or webhook-only job.
scriptPath* string
description string Markdown description of what the job does. Rendered on the job page; a fenced `mermaid` block becomes a diagram. Returned by single-job reads and writes, omitted from lists.
status* JobStatus Allowed: active, paused, deleted
nextRunAt* string | null Next scheduled run for an active job with a cron expression; null for manual, paused, or unscheduled jobs. Format: date-time
lastRunAt string | null Format: date-time
maxAttempts* integer Maximum attempts per run (1 to 5).
autoPauseOnFailure* boolean
consecutiveFailures integer
notifyOnFailure* boolean
autoPaused boolean
createdAt* string Format: date-time

JobResponse

SuccessEnvelope

Property Type Description
data object

CreateJobRequest

object

Property Type Description
name string
cron string | null Cron schedule for the job, evaluated in the account's timezone; see Cron schedules. Omit or null for a manual or webhook-only job.
scriptPath* string
description string Markdown description of what the job does.
maxAttempts integer Maximum attempts per run (1 to 5). Default: 3
autoPauseOnFailure boolean Default: true
notifyOnFailure boolean Default: true
createScript boolean Create the script from the default template when missing. Missing parent directories are created as well. Default: false

UpdateJobRequest

object

Property Type Description
name string | null
cron string | null Cron schedule for the job, evaluated in the account's timezone; see Cron schedules. Null or empty clears the schedule.
scriptPath string
description string | null Markdown description of what the job does. Null or empty clears it.
maxAttempts integer Maximum attempts per run (1 to 5).
autoPauseOnFailure boolean
notifyOnFailure boolean

WebhookEndpoint

object

Property Type Description
id* string
jobId* integer Format: int64
name* string | null
sourceType* string Verification source selected when the endpoint was created.
url* string Absolute inbound URL for the producer. Format: uri
enabled* boolean
createdAt* string Format: date-time
deletedAt* string | null Format: date-time

CreateWebhookRequest

object

Property Type Description
name string Optional display name used in the UI and run history.
sourceType string Verification source. Standard Webhooks base64-decodes the text after the `whsec_` prefix to get the HMAC key; Stripe uses the full `whsec_` string as the key. Paddle and Zendesk sign the timestamp and body. Shopify, GitHub, Square, Typeform, Calendly, Slack, HubSpot, Paddle, and Zendesk use a shared secret. API key and generic HMAC use an arbitrary shared value. Generic HMAC verifies HMAC over the raw request body. Allowed: standard-webhooks, shopify, github, stripe, paddle, square, typeform, calendly, slack, hubspot, zendesk, api-key, unverified, generic-hmac Default: standard-webhooks
secret string Producer-supplied signing secret. Standard Webhooks requires `whsec_` followed by base64 of 24 to 64 bytes. Stripe requires its `whsec_` signing secret and uses the full string as the key. Shopify, GitHub, Square, Typeform, Calendly, Slack, HubSpot, Paddle, Zendesk, API key, and generic HMAC accept a non-empty shared string. API key tokens are limited to 512 characters. Ignored for `unverified`. Write-only.
verification WebhookVerification Source-specific verification overrides. Required for `generic-hmac` and `api-key`; not accepted for presets.

WebhookVerification

object

Source-specific verification overrides. Required for generic-hmac and api-key; not accepted for presets.

Property Type Description
signatureHeader string HTTP header carrying the signature.
algorithm string Allowed: sha1, sha256, sha512 Default: sha256
encoding string Allowed: hex, base64, base64url Default: hex
prefix string Optional prefix expected before the signature value.
idHeader string Optional header carrying a stable delivery ID.
apiKeyHeader string HTTP header carrying the API key or token. Required for `api-key`.
apiKeyPrefix string Optional text expected before the token, including any trailing space, such as `Bearer `.

UpdateWebhookRequest

object

Property Type Description
name string | null Set null or an empty string to clear the name.
enabled boolean

RunJobRequest

object

Property Type Description
env object<string, string> Per-run environment variable overrides.
payload string Optional raw webhook payload for this manual run. The run remains manual and exposes the payload as `context.delivery`. The payload is not sender-verified.

RunQueuedResponse

SuccessEnvelope

Property Type Description
data object
  • runId* string

RunSummary

object

Property Type Description
runId* string Format: uuid
jobId* integer | null Null while the run is queued and has not started. Format: int64
jobName* string | null Null while the run is queued and has not started.
scriptPath string | null
status* RunStatus Allowed: queued, running, retrying, success, error, timeout, interrupted, unknown
eventType string Event recorded for the run, or queued before it starts. Allowed: queued, launched, completed, failed, timeout
attempt integer Attempt number, up to the job's maximum attempts.
attemptCount* integer Number of attempts recorded for the run.
maxAttempts integer Maximum attempts allowed for the run.
trigger string | null manual, webhook, or null for scheduled runs.
webhookEndpointId string | null Endpoint that accepted the run; null for non-webhook runs.
webhookEndpointName string | null Resolved endpoint name, or null when unnamed or purged.
startedAt string | null Run start time, or the accept time while queued. Format: date-time
finishedAt string | null Format: date-time
nextAttemptAt string | null Format: date-time
errorMessage string | null
durationMs integer | null

RunAttempt

object

Property Type Description
attempt* integer Attempt number, starting at 1.
status* RunStatus Allowed: queued, running, retrying, success, error, timeout, interrupted, unknown
startedAt string | null Format: date-time
finishedAt string | null Format: date-time
durationMs integer | null
errorMessage string | null
nextAttemptAt string | null Format: date-time
trigger string | null
logCount* integer Console entries recorded for the attempt.
entries array<ConsoleEntry>

RunLogsResponse

SuccessEnvelope

Property Type Description
data object
  • runId* string
  • status* RunStatus
  • entries* array<RunLogEntry>
  • nextCursor* string | null Pass as `after` to fetch newer entries.
  • hasMore* boolean True when more newer entries remain after this page.
  • totalEntries* integer

RunLogEntry

ConsoleEntry

allOf: ConsoleEntry

Property Type Description
attempt* integer Attempt number, starting at 1.

ConsoleEntry

object

Property Type Description
type* string
timestamp* integer Unix timestamp in milliseconds.
timestampIso string Format: date-time
level* string Allowed: log, info, warn, error, debug
args* array<object>
stack string | null

FileEntry

object

Property Type Description
name* string
path* string
type* string Allowed: file, folder
size integer | null
modifiedAt string | null Format: date-time

CreateFileRequest

object

Property Type Description
parentPath string Default: /
name* string Entry name without slashes.
type* string Allowed: file, folder

UploadFileRequest

object

Property Type Description
parentPath string Directory that receives the file. Default: /
name string Entry name to use instead of the multipart part's filename. Must be a single path segment with no slashes, and must not be "." or "..".
file* string File contents. Format: binary

CreateFileResponse

SuccessEnvelope

Property Type Description
data object
  • name* string
  • path* string
  • type* string

FileContent

object

Property Type Description
path* string
content* string
encoding* string Allowed: utf8, base64
size* integer
offset* integer
returnedBytes* integer
truncated* boolean
modifiedAt string | null Format: date-time

FileMetadata

object

Property Type Description
path* string
type* string Allowed: file, folder
size* integer | null
modifiedAt* string | null Format: date-time

FileWriteRequest

object

Property Type Description
path* string Absolute file path supplied in the JSON body. Query parameters use URL encoding.
content* string UTF-8 file content. The whole JSON request body is capped at 1 MiB (1,048,576 bytes).

FileSavedResponse

SuccessEnvelope

Property Type Description
data object
  • path* string
  • size* integer

RenameFileRequest

object

Property Type Description
path* string
destination* string Full new absolute path, including the final name.

RenameFileResponse

SuccessEnvelope

Property Type Description
data object
  • from* string
  • to* string
  • type* string
  • jobsUpdated* integer
  • jobsUpdateError* string | null

Secret

object

Property Type Description
id* string Format: uuid
name* string
createdAt* string Format: date-time
updatedAt* string Format: date-time

SecretResponse

SuccessEnvelope

Property Type Description
data object

CreateSecretRequest

object

Property Type Description
name* string Must not contain control characters.
value* string

ChangedResponse

SuccessEnvelope

Property Type Description
data object
  • changed* boolean