Directing work over REST

What you will learn How to create, watch, and stop work through /api/v1, and the one thing you must handle when attaching it to automation.

If requests, responses and status codes are unfamiliar, start with Requests and responses — HTTP.

What you did on screen, in code

This does exactly what your first task did on screen, over REST. It calls the same function — work created on screen and work created via the API are indistinguishable.

Five endpoints

Creating a task

What you can send

Omit mode and you get fully automatic. The same default as on screen. For unattended automation you should know what that means before leaving it out.

Where the working directory number comes from

You get numbers along with paths. Do not hardcode the number — look it up by path. Delete and re-register a folder and the number changes.

There is no idempotency key

The most important part of this chapter.

Send the same request twice and you get two tasks.

This is not an omission but a deliberate design. The code comment states the reason — a REST caller only has to send its request once, and we do not pretend to offer a guarantee we do not have.

So what happens in automation

graph TD
  A["Script POSTs"] --> B{"Did a response arrive?"}
  B -->|"yes"| C["Fine"]
  B -->|"timeout"| D["Retry?"]
  D -->|"blind retry"| E["2 tasks created<br/>both edit files"]
  D -->|"check first"| F["Safe"]

A timeout is not the same as a failure. The request may have arrived and only the response been lost. Retrying in that state runs the same work twice.

How to handle it

Using name is the most practical route.

Put the date or a run identifier in the name and you can check whether it already exists before retrying.

The Usage tab shows what this machine spent, and on what.

Watching progress

Creating a task returns an identifier. Use it to poll.

For long-running work, poll generously. Prodding every second gains nothing.

Follow-up and stop

Always wire stop into automation. Agents go just as hard in the wrong direction. In unattended automation, something has to stop it when it exceeds a time or cost ceiling.

Where to use it

For regular runs, scheduling beats this API. Keeping the scheduler inside the system is easier to manage than one outside. Use the API when an outside event is the trigger.

Attaching it safely

The first line matters most. Once automation starts editing files it is hard to undo, and hard to even verify without a git commit.

Check yourself

1. What happens if you send the same POST twice?

2. What autonomy level do you get if you omit mode?

3. Why is this API second-best for regular runs?

Drive one yourself, duplicate run included. Forty minutes → Drive a job over REST