Quickstart: scripts

This walks through a typical automation flow: authenticate, find a project, create an issue, and check session status — all with curl and jq.

1. Set your token

Create a scoped token (see Authentication) and export it:

export HALYARD_TOKEN="hly_…"
export HALYARD_API="https://api.halyard-ai.com/api/v1"

For a script that reads and files issues, projects:read + issues:write is enough.

2. List projects

curl -s "$HALYARD_API/projects" \
  -H "Authorization: Bearer $HALYARD_TOKEN" | jq '.data[] | {id, name}'

Projects can be addressed by name or id in the path.

3. Create an issue

curl -s "$HALYARD_API/projects/my-project/issues" \
  -H "Authorization: Bearer $HALYARD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Flaky test in CI", "type": "bug" }' | jq '{number, title, status}'

4. Check session status

List a project’s agent sessions and read their state:

curl -s "$HALYARD_API/projects/my-project/sessions" \
  -H "Authorization: Bearer $HALYARD_TOKEN" | jq '.data[] | {id, state}'

# A single session's current status:
curl -s "$HALYARD_API/sessions/<session-id>" \
  -H "Authorization: Bearer $HALYARD_TOKEN" | jq '{id, state}'

5. Handle errors and limits

Check the HTTP status and the error code (see Errors). Respect 429 by waiting for Retry-After:

resp=$(curl -s -w '\n%{http_code}' "$HALYARD_API/projects" \
  -H "Authorization: Bearer $HALYARD_TOKEN")
code=$(tail -n1 <<<"$resp"); body=$(sed '$d' <<<"$resp")
[ "$code" = "200" ] || { echo "error $code: $(jq -r .error <<<"$body")"; exit 1; }

Next: the full endpoint list is in the API reference, where you can also try requests live.