The Gradelog REST API enables contractors and software developers to integrate field documentation, grade verification, and as-built reporting directly into their own workflows, platforms, and back-office systems. Automate job creation, stream grade readings into your data pipeline, trigger as-built report generation on job completion, and keep your equipment registry in sync — all without touching the Gradelog web interface.
The API follows REST conventions, uses JSON for request and response bodies, and authenticates via bearer tokens. Endpoints are versioned under /api/v1/ to ensure your integrations remain stable as Gradelog evolves. API access is available on Company ($249/mo) and Enterprise plans.
All API requests require a bearer token. Generate an API key from your Gradelog account under Settings → API Keys. Include the key in every request as an Authorization header. Keys are prefixed with sk_gradelog_ and should be treated as secrets — never commit them to source control or expose them in client-side code.
Authorization: Bearer sk_gradelog_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxRequests without a valid token return 401 Unauthorized. Requests to endpoints outside your plan return 403 Forbidden.
The following endpoints are planned for the initial API release. All endpoints return JSON. Timestamps are ISO 8601 in UTC. Pagination uses cursor-based after and limit parameters.
/api/v1/jobsLiveList all jobs in your organization. Returns job metadata, status, and timestamps.
/api/v1/jobsPlannedCreate a new job. Accepts job name, location, equipment assignment, and project type.
/api/v1/jobs/{id}/shotsLiveRetrieve all grade shots logged for a specific job, including point name, station, elevation, coordinates and timestamps.
/api/v1/jobs/{id}/shotsPlannedLog a new grade shot for a job. Accepts elevation, design grade, station, and offset.
/api/v1/jobs/{id}/reportPlannedGenerate or retrieve the as-built report for a job. Returns a signed PDF URL valid for 24 hours.
/api/v1/equipmentPlannedList all equipment registered to your organization, including calibration status and last verified date.
/api/v1/equipmentPlannedRegister a new piece of equipment. Accepts make, model, serial number, and calibration interval.
Base URL: https://gradelog.com
API requests are rate-limited per organization. When you exceed the limit, the API returns 429 Too Many Requests with a Retry-After header indicating when to retry.
Need higher throughput? Contact us to discuss custom limits for high-volume integrations.
Gradelog can push real-time event notifications to your endpoint via HTTP POST. Configure webhook URLs in your account settings. Each delivery includes an HMAC-SHA256 signature so you can verify the payload is from Gradelog.
job.completedFired when a job is marked complete. Includes job ID, summary stats, and as-built report URL.
shot.loggedFired each time a grade shot is recorded. Includes elevation, design grade, pass/fail, and timestamps.
report.generatedFired when an as-built report is successfully generated. Includes a signed PDF URL.
Authenticate and list jobs
curl https://gradelog.com/api/v1/jobs \
-H "Authorization: Bearer sk_gradelog_xxxxxxxxxxxxxxxx" \
-H "Accept: application/json"Create a job
curl -X POST https://gradelog.com/api/v1/jobs \
-H "Authorization: Bearer sk_gradelog_xxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"name": "Main St Sewer Lateral — Sta 0+00 to 4+50",
"project_type": "sewer",
"equipment_id": "equip_abc123"
}'Log a grade shot
curl -X POST https://gradelog.com/api/v1/jobs/job_xyz789/shots \
-H "Authorization: Bearer sk_gradelog_xxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"elevation": 312.47,
"design_grade": 312.50,
"station": "1+25",
"offset": "0.0"
}'API access is included in Company ($249/mo) and Enterprise plans. Start your free trial to explore the platform, or contact sales to discuss an Enterprise integration.
Questions? Email api@gradelog.com