Drive a job over REST

What you will learn Not a chapter to read but one to do. Start one job over REST, read its progress, and send it twice on purpose to see what happens.

What you need

text

□ 40 minutes□ HyperTeams running, with one registered working directory□ curl, or any HTTP client□ A token□ Start with a directory that is easy to restore

If you have not issued a token yet, directing work over REST covers how.

Do not paste the token into a chat or an issue. Keep it inside the terminal for the whole exercise.

Step 1 — Read before you write (5 min)

Before creating a job, confirm a read call works. This keeps authentication problems and request problems from getting mixed up later.

text

□ You called the list endpoint once□ You got a 200□ On 401/403 -> a token problem. Fix it here before moving on

If you are stuck here, do not go to step 2. Carrying an auth problem into job creation gives you two causes at once.

Step 2 — Start a read-only job (10 min)

Make the first job one that changes no files.

text

Example instruction:  "List the files in this folder that have no tests. Do not modify any files."

What to look for

text

□ Does the response contain a job id?□ Can you query progress with that id?□ Does the same job appear on the dashboard?  <- both surfaces see one thing

The third one matters. Seeing with your own eyes that REST and the screen show the same job saves you the later "where do I see the ones I started from code?"

Step 3 — Read the progress (5 min)

Poll the same job a few times until it finishes.

Check
Does the state value change?	□
Where do you read the result when it ends?	□
If it failed, is the reason in the response?	□

text

□ How many seconds between polls — write it down

Write that last one down. When you automate this later, that interval becomes your design value: too frequent is pure load, too sparse is a slow reaction.

Step 4 — Send it twice on purpose (15 min)

This is the point of the exercise. Send the same request twice in a row.

text

□ You called it twice with an identical body

What to look for

What happened	What it means
Two jobs appeared	that is correct behaviour. And that is the problem
Only one appeared	something blocked it — find out what

There are no idempotency keys. Send it twice and it runs twice. It was harmless here because the job only reads — but had it been an email send, two emails would have gone out.

So what do you do

The caller has to prevent it. Pick whichever fits your situation.

text

□ Before sending, query whether a job with the same instruction is already running□ Generate a request key on your side and never resend a key you already sent□ Retry only on a confirmed failure   <- a timeout is not a failure

The third line causes the most incidents. A slow response gets read as a failure and resent, while the server is still happily processing the first one.

Step 5 — Tidy up (5 min)

text

□ You cleaned up the practice jobs□ You checked the token did not end up in a record (shell history included)□ You wrote down the poll interval and your duplicate-prevention approach

Self-check

text

□ You confirmed auth with a read call first□ You confirmed REST and the screen show the same job□ You saw two jobs appear from the same request twice  <- if not, back to step 4□ You picked a way to prevent duplicates

Check yourself

1. Why call a read endpoint before creating a job?

Answer

To separate auth problems from request problems. If the read works, the token is fine, so any later error is in the request body.

2. Why do two identical requests create two jobs?

Answer

There are no idempotency keys. The server treats them as separate requests. Deduplication has to happen on the calling side.

3. What is wrong with retrying on a timeout?

Answer

A timeout may be a slow response, not a failure. If the second request arrives while the server is still processing the first, the same work runs twice.

Now open the door on the model side → Getting models — downloading and running them