Using the REST API#

The REST API lets your own tools work with the same account as the workbench. Use it from a server, a CI job, or an automation script to manage jobs, read run history, work with files and secrets, manage webhook endpoints, and check plan usage.

Create a Token#

  1. Open Settings, then click Manage API Tokens.
  2. Under Create a token, enter a name.
  3. Select the scopes the integration needs, then choose an expiry.
  4. Click Create token.
  5. On the API Token Created page, click Copy and store the value.

The token is shown once. Keep it out of source control. You can have up to 20 active tokens, each valid for at most 365 days. Revoke a token from the same page when an integration no longer needs access.

Make a Request#

Send the token as a bearer credential. The production base URL is https://app.geartrain.dev/api/v1.

export GEARTRAIN_API_TOKEN="gt_pat_..."
curl "https://app.geartrain.dev/api/v1/jobs" \
  -H "Authorization: Bearer $GEARTRAIN_API_TOKEN"

Successful responses have an ok flag, a requestId, and a data object. Failures use the same shape with an error object.

Scopes#

Each token grants only the scopes you select. Write access does not imply read access, so select both when an integration needs to read and change the same resource. The token form lists every scope and what it allows, and the REST API reference documents the scope required by each operation.

Webhook Endpoints#

Webhook endpoints are managed under /jobs/{jobId}/webhooks. Reading them requires jobs:read; creating, updating, and deleting them requires jobs:write. The secret is supplied by the sender and is never returned. See the REST API reference for the request and response shapes, Webhooks for the delivery contract, and Webhook Verification for the supported methods.

Limits#

  • API requests are limited per account. If you exceed the limit, the API returns 429 and a Retry-After header with the number of seconds to wait before retrying.
  • Mutations accept an Idempotency-Key, so a retry does not repeat the change.
  • The API is for server-side clients. It does not send CORS headers, so browsers cannot call it cross-origin.

Next Steps#