Queue a structural Browser action

curl --request POST \
  --url https://api.checkfu.com/v1/computers/{id}/screens/{screen_id}/actions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'checkfu-version: <checkfu-version>' \
  --data '
{
  "source_observation_id": "<string>",
  "action": {
    "type": "click",
    "locator": {
      "type": "role",
      "role": "<string>",
      "accessible_name": "<string>"
    }
  },
  "deadline": "<string>"
}
'

import requests

url = "https://api.checkfu.com/v1/computers/{id}/screens/{screen_id}/actions"

payload = {
    "source_observation_id": "<string>",
    "action": {
        "type": "click",
        "locator": {
            "type": "role",
            "role": "<string>",
            "accessible_name": "<string>"
        }
    },
    "deadline": "<string>"
}
headers = {
    "checkfu-version": "<checkfu-version>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'checkfu-version': '<checkfu-version>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    source_observation_id: '<string>',
    action: {
      type: 'click',
      locator: {type: 'role', role: '<string>', accessible_name: '<string>'}
    },
    deadline: '<string>'
  })
};

fetch('https://api.checkfu.com/v1/computers/{id}/screens/{screen_id}/actions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.checkfu.com/v1/computers/{id}/screens/{screen_id}/actions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'source_observation_id' => '<string>',
    'action' => [
        'type' => 'click',
        'locator' => [
                'type' => 'role',
                'role' => '<string>',
                'accessible_name' => '<string>'
        ]
    ],
    'deadline' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "checkfu-version: <checkfu-version>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.checkfu.com/v1/computers/{id}/screens/{screen_id}/actions"

	payload := strings.NewReader("{\n  \"source_observation_id\": \"<string>\",\n  \"action\": {\n    \"type\": \"click\",\n    \"locator\": {\n      \"type\": \"role\",\n      \"role\": \"<string>\",\n      \"accessible_name\": \"<string>\"\n    }\n  },\n  \"deadline\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("checkfu-version", "<checkfu-version>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.checkfu.com/v1/computers/{id}/screens/{screen_id}/actions")
  .header("checkfu-version", "<checkfu-version>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"source_observation_id\": \"<string>\",\n  \"action\": {\n    \"type\": \"click\",\n    \"locator\": {\n      \"type\": \"role\",\n      \"role\": \"<string>\",\n      \"accessible_name\": \"<string>\"\n    }\n  },\n  \"deadline\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.checkfu.com/v1/computers/{id}/screens/{screen_id}/actions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["checkfu-version"] = '<checkfu-version>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"source_observation_id\": \"<string>\",\n  \"action\": {\n    \"type\": \"click\",\n    \"locator\": {\n      \"type\": \"role\",\n      \"role\": \"<string>\",\n      \"accessible_name\": \"<string>\"\n    }\n  },\n  \"deadline\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "envelope": {
    "id": "<string>",
    "workspace_id": "<string>",
    "computer_id": "<string>",
    "expected_computer_generation": 1,
    "screen_id": "<string>",
    "attachment_id": "<string>",
    "session_id": "<string>",
    "run_id": "<string>",
    "run_attempt_id": "<string>",
    "acting_principal_id": "<string>",
    "expected_control_epoch": 1,
    "expected_observation_generation": 1,
    "source_observation_id": "<string>",
    "action": {
      "type": "navigate",
      "destination_digest": "<string>"
    },
    "policy_context_digest": "<string>",
    "action_approval_context_digest": "<string>",
    "usage_budget_context_digest": "<string>",
    "requested_at": "<string>",
    "deadline": "<string>"
  },
  "action_fingerprint": "<string>",
  "destination_decision": {
    "status": "allow",
    "rule_key": "<string>",
    "purpose": "navigate",
    "policy_digest": "<string>",
    "destination_digest": "<string>",
    "decided_at": "<string>"
  },
  "admitted_at": "<string>"
}

{
  "error": {
    "type": "validation.malformed",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#validation-malformed"
  }
}

{
  "error": {
    "type": "auth.invalid_key",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#auth-invalid-key"
  }
}

{
  "error": {
    "type": "auth.disabled_tenancy",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#auth-disabled-tenancy"
  }
}

{
  "error": {
    "type": "validation.not_found",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#validation-not-found"
  }
}

{
  "error": {
    "type": "validation.conflict",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#validation-conflict"
  }
}

{
  "error": {
    "type": "budget.exceeded",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#budget-exceeded"
  }
}

{
  "error": {
    "type": "runtime.internal",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#runtime-internal"
  }
}

Queue a structural Browser action

Queues one caller-minimal structural action for the exact Computer Screen. The caller selects only click, keypress, scroll, target switch, or target close plus a required source observation where stale DOM matters and a short deadline. The owning Session freezes the live RunAttempt and derives every Computer, Screen, attachment, actor, profile, ActionPolicy, ActionApproval, and UsageBudget coordinate before any provider contact. When ActionPolicy requires approval, the first attempt creates one exact durable Browser ActionApproval and admits no action; after a human decision, retry the identical request with the same Idempotency-Key so the Session re-evaluates current policy, rejoins only the matching approved decision, and persists the action. Navigation destinations and transient text cannot fit this operation.

Checkfu support posture: alpha; hosted. No release evidence journey applies to this operation.

POST

computers

{id}

screens

{screen_id}

actions

Queue a structural Browser action

curl --request POST \
  --url https://api.checkfu.com/v1/computers/{id}/screens/{screen_id}/actions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'checkfu-version: <checkfu-version>' \
  --data '
{
  "source_observation_id": "<string>",
  "action": {
    "type": "click",
    "locator": {
      "type": "role",
      "role": "<string>",
      "accessible_name": "<string>"
    }
  },
  "deadline": "<string>"
}
'

import requests

url = "https://api.checkfu.com/v1/computers/{id}/screens/{screen_id}/actions"

payload = {
    "source_observation_id": "<string>",
    "action": {
        "type": "click",
        "locator": {
            "type": "role",
            "role": "<string>",
            "accessible_name": "<string>"
        }
    },
    "deadline": "<string>"
}
headers = {
    "checkfu-version": "<checkfu-version>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'checkfu-version': '<checkfu-version>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    source_observation_id: '<string>',
    action: {
      type: 'click',
      locator: {type: 'role', role: '<string>', accessible_name: '<string>'}
    },
    deadline: '<string>'
  })
};

fetch('https://api.checkfu.com/v1/computers/{id}/screens/{screen_id}/actions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.checkfu.com/v1/computers/{id}/screens/{screen_id}/actions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'source_observation_id' => '<string>',
    'action' => [
        'type' => 'click',
        'locator' => [
                'type' => 'role',
                'role' => '<string>',
                'accessible_name' => '<string>'
        ]
    ],
    'deadline' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "checkfu-version: <checkfu-version>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.checkfu.com/v1/computers/{id}/screens/{screen_id}/actions"

	payload := strings.NewReader("{\n  \"source_observation_id\": \"<string>\",\n  \"action\": {\n    \"type\": \"click\",\n    \"locator\": {\n      \"type\": \"role\",\n      \"role\": \"<string>\",\n      \"accessible_name\": \"<string>\"\n    }\n  },\n  \"deadline\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("checkfu-version", "<checkfu-version>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.checkfu.com/v1/computers/{id}/screens/{screen_id}/actions")
  .header("checkfu-version", "<checkfu-version>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"source_observation_id\": \"<string>\",\n  \"action\": {\n    \"type\": \"click\",\n    \"locator\": {\n      \"type\": \"role\",\n      \"role\": \"<string>\",\n      \"accessible_name\": \"<string>\"\n    }\n  },\n  \"deadline\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.checkfu.com/v1/computers/{id}/screens/{screen_id}/actions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["checkfu-version"] = '<checkfu-version>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"source_observation_id\": \"<string>\",\n  \"action\": {\n    \"type\": \"click\",\n    \"locator\": {\n      \"type\": \"role\",\n      \"role\": \"<string>\",\n      \"accessible_name\": \"<string>\"\n    }\n  },\n  \"deadline\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "envelope": {
    "id": "<string>",
    "workspace_id": "<string>",
    "computer_id": "<string>",
    "expected_computer_generation": 1,
    "screen_id": "<string>",
    "attachment_id": "<string>",
    "session_id": "<string>",
    "run_id": "<string>",
    "run_attempt_id": "<string>",
    "acting_principal_id": "<string>",
    "expected_control_epoch": 1,
    "expected_observation_generation": 1,
    "source_observation_id": "<string>",
    "action": {
      "type": "navigate",
      "destination_digest": "<string>"
    },
    "policy_context_digest": "<string>",
    "action_approval_context_digest": "<string>",
    "usage_budget_context_digest": "<string>",
    "requested_at": "<string>",
    "deadline": "<string>"
  },
  "action_fingerprint": "<string>",
  "destination_decision": {
    "status": "allow",
    "rule_key": "<string>",
    "purpose": "navigate",
    "policy_digest": "<string>",
    "destination_digest": "<string>",
    "decided_at": "<string>"
  },
  "admitted_at": "<string>"
}

{
  "error": {
    "type": "validation.malformed",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#validation-malformed"
  }
}

{
  "error": {
    "type": "auth.invalid_key",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#auth-invalid-key"
  }
}

{
  "error": {
    "type": "auth.disabled_tenancy",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#auth-disabled-tenancy"
  }
}

{
  "error": {
    "type": "validation.not_found",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#validation-not-found"
  }
}

{
  "error": {
    "type": "validation.conflict",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#validation-conflict"
  }
}

{
  "error": {
    "type": "budget.exceeded",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#budget-exceeded"
  }
}

{
  "error": {
    "type": "runtime.internal",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#runtime-internal"
  }
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

checkfu-version

enum<string>

required

Available options:

2026-08-27

idempotency-key

string

Maximum string length: 255

Path Parameters

string

required

Pattern: ^comp_[0-9a-f]{32}$

screen_id

string

required

Pattern: ^scrn_[0-9a-f]{32}$

Body

application/json

source_observation_id

string | null

required

Pattern: ^bobs_[0-9a-f]{32}$

action

object

required

Option 1
Option 2
Option 3
Option 4
Option 5

Show child attributes

deadline

string

required

A canonical UTC ISO-8601 timestamp with millisecond precision.

Maximum string length: 24

Pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$

Response

Success

envelope

object

required

Show child attributes

action_fingerprint

string

required

Pattern: ^sha256:[0-9a-f]{64}$

destination_decision

object

required

Option 1
Option 2

Show child attributes

admitted_at

string

required

A canonical UTC ISO-8601 timestamp with millisecond precision.

Maximum string length: 24

Pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$

Developer tools

Canonical tables

Author protocols

Generated HTTP API

Queue a structural Browser action

Authorizations

Headers

Path Parameters

Body

Response