Scout's page only: show a job's folder in the file manager

POST

/api/jobs-folder/open

curl --request POST \
  --url http://127.0.0.1:8765/api/jobs-folder/open \
  --header 'Content-Type: application/json' \
  --data '{}'

Scout’s own page only: show the jobs folder, or one job’s folder, in the computer’s file manager. NOT for agents: it answers only Scout’s own browser page (a request carrying this server’s own Origin); any other caller gets 403 forbidden_origin and nothing is opened. The request never carries a folder path: GigAI finds the folder itself, from the stored job (or from the jobs folder setting), and refuses one that is not inside the jobs folder (422 outside_jobs_folder). A job GigAI has made no folder for, or a folder that is not there, answers 404 folder_missing. It asks the computer to show the folder (macOS open, Linux xdg-open when there is a desktop); the answer is 200 either way: opened false means this computer could not, and message says so in one plain sentence that names the folder so the person can copy it. It shows the folder only: no file is read or changed.

Request Body

Media typeapplication/json

object

job_identity

Optional: the job whose folder to open (the page’s own identity). Without it, the jobs folder itself is opened.

string

profile_id

Optional; taken with job_identity and picks nothing (0.1.11.9: the job names its folder).

string

Example

{}

Responses

200

Success.

Media typeapplication/json

object

schema_version

required

Allowed value: scout-jobs-folder-open:1

key

additional properties

any

Example

{
  "message": "Opened ~/Documents/GigAI/jobs/acme/staff-engineer.",
  "opened": true,
  "schema_version": "scout-jobs-folder-open:1",
  "shown": "~/Documents/GigAI/jobs/acme/staff-engineer"
}

403

Forbidden_origin

Media typeapplication/json

object

error

required

object

allowed_keys

Array<string>

code

required

string

message

required

string

key

additional properties

any

Example

{
  "error": {
    "code": "forbidden_origin",
    "message": "..."
  }
}

404

Folder_missing, target_unavailable

Media typeapplication/json

object

error

required

object

allowed_keys

Array<string>

code

required

string

message

required

string

key

additional properties

any

Example

{
  "error": {
    "code": "folder_missing",
    "message": "..."
  }
}

415

Unsupported_media_type: writes need Content-Type: application/json.

Media typeapplication/json

object

error

required

object

allowed_keys

Array<string>

code

required

string

message

required

string

key

additional properties

any

Example^generated

{
  "error": {
    "allowed_keys": [
      "example"
    ],
    "code": "example",
    "message": "example"
  }
}

422

Unknown_key, wrong_type, invalid_value, outside_jobs_folder

Media typeapplication/json

object

error

required

object

allowed_keys

Array<string>

code

required

string

message

required

string

key

additional properties

any

Example

{
  "error": {
    "code": "unknown_key",
    "message": "..."
  }
}