Build a PingStep integration with an AI assistant

Give this page or llms.txt to ChatGPT, Copilot, Claude, or your coding agent. It explains the safe, small contract needed to report job progress.

Do not put a job token in a prompt, source file, issue, or chat. Store it in the job environment or your approved secret store, then refer to it as PINGSTEP_TOKEN.

What an agent should add

Read PINGSTEP_URL and PINGSTEP_TOKEN from environment variables.
Create one unique run ID when the job begins.
Send started with sequence 1.
Send step for a meaningful checkpoint and heartbeat when work continues without a new checkpoint.
Send exactly one succeeded after useful work is complete, or failed with a safe message when the script handles an error.

Event shape

{
  "event_id": "unique-event-id",
  "job_key": "non-sensitive-job-name",
  "run_id": "unique-run-id",
  "sequence": 2,
  "type": "step",
  "occurred_at": "2026-08-02T12:00:00Z",
  "data": { "name": "processing files" }
}

POST this JSON to https://pingstep.dev/v1/events with Authorization: Bearer $PINGSTEP_TOKEN and Content-Type: application/json.

Rules an agent must preserve

Use the same event_id and identical event body when retrying a delivery.
Use a new event ID and a higher sequence number for new information.
Do not send logs, credentials, SQL, command output, customer records, or personal data.
Stale is not failed. Stale means PingStep stopped receiving updates. It cannot know why. Do not fabricate a terminal event after a process is killed or loses network access.
Do not report success until the script has actually finished the work it owns.

Prompt starter

Instrument this script with PingStep lifecycle events. Read PINGSTEP_URL and PINGSTEP_TOKEN from the environment. Generate unique run_id and event_id values. Send started, meaningful step or heartbeat events, then succeeded or failed only when the script knows the outcome. Never log or expose the token. Never treat a missing update as failure.

For general event details, read the event guide. Create a job and retrieve its one-time token from the dashboard.